








                           THE ADVENTURE GAME TOOLKIT




                                       BY

                                DAVID R. MALMBERG

                                       AND

                                  MARK J. WELCH




THE ADVENTURE GAME TOOLKIT IS NOW "FREEWARE"

AGT is now "freeware."  This means that the authors, David Malmberg and Mark
Welch, still retain the copyright to AGT and all of its related files, such
as the documentations and sample games.  However, you or any other user may
use the AGT system to develop and distribute your own games without paying any
royalty to the AGT authors.

So enjoy!!


                                                                              2

COPYRIGHT, TRADEMARKS AND WARRANTY


COPYRIGHT:
The Adventure Game Toolkit is a copyrighted work, just like a book.  It is
protected by United States copyright law and by applicable international
treaty provisions.  All text, program, and source code files on disk(s) are
copyright 1987, 1988, 1989, 1990 and 1992 by Mark J. Welch and David R.
Malmberg.  Portions of the manual and source code are copyright 1985 and 1986
by Mark J. Welch.


TRADEMARKS:
"Adventure Game Toolkit" and "AGT" are trademarks of Mark J. Welch and
David R. Malmberg.


WARRANTY:
The program disk(s) and printed manual are warranted to be free from
defects in materials and workmanship for a period of 90 days from the date
of purchase.  In the event of a defect, registered users of AGT may obtain
a replacement copy of the program disk(s) and/or manual from Softworks. 
The remedy for any breach of warranty shall be limited to replacement or
refund and shall not encompass any other damages, including but not limited
to loss of profit, special, incidental, consequential, or other similar
claims.


DISCLAIMER:
THE ADVENTURE GAME TOOLKIT (AGT) COMES WITH NO OTHER WARRANTIES OF ANY
KIND, INCLUDING WARRANTY OF MERCHANTABILITY OR OF FITNESS FOR A PARTICULAR
PURPOSE. THE ADVENTURE GAME TOOLKIT (AGT) IS AVAILABLE AS IS. IN NO EVENT
WILL THE AUTHORS BE LIABLE FOR DAMAGES, INCLUDING ANY LOST PROFITS OR
INCIDENTAL AND CONSEQUENTIAL DAMAGES, EVEN IF THE AUTHORS HAVE BEEN ADVISED
OF THE POSSIBILITY OF SUCH DAMAGES.


Softworks is a member of the Association of Shareware Professionals -- your
guarantee of quality in shareware software.

                            _______
                       ____|__     |               (tm)
                    --|       |    |-------------------
                      |   ____|__  |  Association of
                      |  |       |_|  Shareware
                      |__|   o   |    Professionals
                    -----|   |   |---------------------
                         |___|___|    MEMBER


                                                                              3

QUICK START


THE FILES ON THE DISK(S)

On the disk(s) included with this documentation are a number of files. 
Specifically, the disk(s) have the Adventure Game Toolkit's COMPILE and RUN
programs, a number of sample adventure game source files, some "utility"
programs, the latest documentation, and one or more "README" files. 

However, all of these files (except the README files) on the disk(s) are in
a "compressed" form.  By doing this, we were able to put the equivalent of
five 360K disks worth of material on only two 360K disks.  The compression
form various from computer to computer.  The IBM files have been "ZIPped";
the Macintosh files have been "Stuffed"; and the Atari ST files have been
"ARCed."  However, the means to "uncompress" your files has also been
included on your disks.  To learn how to do this, simply run or browse the
README file.  This file will explain in detail what steps you should follow
to create an "uncompressed", fully-useable version of the Adventure Game
Toolkit (AGT).


CREATING A PLAYABLE VERSION OF ONE OF THE SAMPLE GAMES

To create a playable version of one of the sample adventure games on your
disk you will first need to COMPILE the game's source files and then RUN
the compiled game using AGT's COMPILE and RUN programs.  The detailed steps
needed to do this for an IBM or compatible computer are described in a
section of the manual beginning on page 17.  For Macintosh and Atari ST
computers -- check out Appendix F.


CREATING YOUR OWN ADVENTURE GAME

When creating your source data files for your own AGT game, you must use a
text editor or word processor which creates plain ASCII or TEXT files with
a true carriage return at the end of each line.  Lines longer than 80
characters, WordStar or WordPerfect document files, will cause AGT to
abort!  The best rule-of-thumb is to use the MS-DOS "TYPE" command to view
the file.  If it looks normal, it's probably OK for AGT.  If words split at
the end of the line and strange characters appear, it's probably not OK for
AGT.

If you are using a Macintosh or Atari ST, your word processor or text
editor will have an option to save the file as an ASCII or TEXT file with
real carriage returns (sometimes called "line breaks") and without any
embedded "formatting" characters.  This is the option you should use.  For
example, if you are using Microsoft Word on the Macintosh, you would select
"SAVE AS" from the File Menu, then click the button that is labeled "File
Format...", then select the option that is says "Text Only With Line
Breaks."  Or another example -- if you are using MacWrite on the Macintosh,
you would select "SAVE AS" from the File Menu, then click the button that

                                                                              4

is labeled "Text Only."  Other word processor will have similar options
when you save your game source files.

Obviously, you will need to know what to put into your AGT source files in
order to create your own adventure game.  Unfortunately, there is no "quick
start" for doing this -- other than reading the documentation.  If you are
anxious to start your own adventure game and want to read as little as
possible to get started, read sections 1 and 2 of the manual.  These
sections should tell you enough to get you started.  However, read the
other sections of the manual later or you will really miss out on
discovering just how much power AGT can give you to creating truly
professional level, world-class games.


SECTIONS OF THE MANUAL

PART 1 gives an overview of the Adventure Game Toolkit, the various files
on the disk(s), and explains how to play the adventure games created by the
AGT.

PART 2 gives a number of pointers on how to create a good adventure game. 
It also explains the way AGT defines an adventure game in terms of files
and game data elements like Rooms, Nouns, and Creatures and gives several
examples of each.

PART 3 explains the use of AGT's unique meta-language and how it can be
used to create Professional Level adventure games.  Numerous examples are
given.

PART 4 gives several detailed scenarios where meta-language commands have
been used to create typical adventure games situations, like random attacks
by other characters, and how to expand the game's vocabulary to include new
verbs and actions.

PART 5 gives a number of helpful "secret" commands for "debugging" your
game once you have a first draft.

The final part of the manual is a series of Appendices that give detailed
information on a number of specific AGT topics for easy reference.


HARDWARE REQUIREMENTS FOR AGT

The games created by the Adventure Game Toolkit requires an IBM-compatible
computer with at least 384K of memory, MS-DOS 2.1, and at least one disk
drive.  You may use any kind of monitor and AGT will automatically adjust
its output to best suit your monitor.  See Appendix F for Macintosh and
Atari ST hardware requirements.

                                                                              5


THE ADVENTURE GAME TOOLKIT IS NOW "FREEWARE"

AGT is now "freeware."  This means that the authors, David Malmberg and Mark
Welch, still retain the copyright to AGT and all of its related files, such
as the documentations and sample games.  However, you or any other user may
use the AGT system to develop and distribute your own games without paying any
royalty to the AGT authors.

So enjoy!!

                                                                              6


THE ADVENTURE GAME TOOLKIT IS NOW "FREEWARE"

AGT is now "freeware."  This means that the authors, David Malmberg and Mark
Welch, still retain the copyright to AGT and all of its related files, such
as the documentations and sample games.  However, you or any other user may
use the AGT system to develop and distribute your own games without paying any
royalty to the AGT authors.

So enjoy!!

                                                                              7

END-USER LICENSE TERMS (Shareware Rules)

The Adventure Game Toolkit (AGT) is NOT public domain or free software, but
is being distributed as "Shareware".  This means that if you are a regular
user of AGT, you should pay for your copy and become a registered user. 
Only from the income from your registration fees can the authors continue
to provide product support, make enhancements to AGT, and stay in business.

Non-registered users of this software are granted a limited license to make
an evaluation copy for trial use on a private non-commercial basis, for the
express purpose of determining whether AGT is suitable for their needs.  At
the end of this trial period, the user should either register his/her copy
of AGT or discontinue using it.

Registered users of AGT may use AGT on any computer, provided that AGT is
used on only one computer at a time, and that the copy is not routinely
used on that computer by other people.  If other people use the copy of AGT
routinely, they should become registered users themselves.  Registered AGT
users may make archival and working copies of the AGT program disk(s) to
back up their software and protect their investment.  They may also make
evaluation copies of AGT for trial use by non-registered users, subject to
the terms outlined above.

Operators of electronic bulletin boards (Sysops) are encouraged to post the
Adventure Game Toolkit and related Adventure Game files for downloading by
their users.  However, if these bulletin boards also offer AGT-based games
for "On-Line" or "Doors" play, these Sysops should register their copy of
AGT because they are using AGT on a routine basis.

This license to use AGT does NOT include the right to distribute or sell
AGT.  Distribution terms are detailed below.

AGT or AGT produced games may be uploaded to and downloaded from commercial
systems such as CompuServe, GEnie, and BIX, so long as the only charge paid
by the subscriber is for on-line time and there is no charge for the
program.  Those copying, sharing, and/or electronically transmitting the
program are required not to delete or modify the copyright notice and
restrictive notices from the program or documentation; anyone doing so will
be treated as a contributory copyright violator.

The Adventure Game Toolkit documentation may not be modified by users. The
program may not be separated from the documentation when distributed. 
Printed or "Xeroxed" copies of the AGT documentation (i.e., this manual)
may not be distributed or sold without the written permission of Softworks.

NOTE:  This program is produced by a member of the Association of Shareware
Professionals (ASP).  ASP wants to make sure that the shareware principle
works for you.  If you are unable to resolve a shareware-related problem
with an ASP member by contacting the member directly, ASP may be able to
help.  The ASP Ombudsman can help you resolve a dispute with an ASP member,
but does not provide technical support for members' products.  Please write
to the ASP Ombudsman at P.O. Box 5786, Bellevue, WA 98006 or send a

                                                                              8

CompuServe message via EasyPlex to ASP Ombudsman 70007,3536.


Distribution of AGT by game authors:

Authors of AGT games may distribute the AGT "driver" program, RUN.EXE, with
their games for the purpose of playing games written using the Adventure
Game Toolkit.  If the game will be widely distributed, we ask that you
request written permission and send us a copy of your game so we can notify
you of updates or changes to AGT, especially changes that may affect your
game.  If your game will be commercially distributed, you must obtain a
written license to distribute RUN.EXE; there is a one-time fee of $10 for
this license for commercial distribution.


Distribution of AGT by disk vendors and computer dealers:

Distributors of "public domain" or user-supported software libraries must
obtain written permission to distribute copies of AGT and related adventure
game files.  No one may use AGT as a promotion for any commercial venture
or as an enticement for the user to pay for any program, product, or
service unless they have received the express written permission of the
program's authors.

In order to distribute AGT, a dealer or disk vendor must comply with the
following conditions:

      (1)  You must obtain written permission from Softworks to distribute
           AGT. If you receive no reply, write again: our silence does NOT
           constitute permission, and you may not distribute "pending"
           receipt of permission.

      (2)  A fee of not more than $7 may be charged for each disk sold. 
           This includes "multi-disk" volumes: AGT may not be included on
           any disk sold for more than $7, including CD-ROM or optical
           disks, without express written permission from Softworks.

      (3)  Vendors may not modify or delete ANY files on the disk.  Vendors
           may add a "GO" program, and/or a reasonable number of small text
           files designed to assist or provide a service to the user, but
           these added files must be easily identifiable and end-users must
           be allowed to delete the added files.

      (4)  Vendors must make a reasonable effort to distribute only the most
           recent versions of AGT.  All vendors who have requested and
           received written permission to distribute AGT will be notified of
           updates as they are released.

      (5)  All disk vendors must comply with any and all vendor guidelines
           or vendor requirements set forth by the Association of Shareware
           Professionals (ASP).

                                                                              9

           These ASP guidelines essentially call for the following:  Vendors
           must make an attempt to educate users on the nature of Shareware. 
           Catalogs, advertisements, order forms, and all disks sold should
           contain ASP-approved or recommended wording describing the nature
           of shareware, and should explicitly state that no part of disk
           sale revenues are paid to the programs' authors.  Vendors may not
           advertise under the heading "Public Domain Software", "Free
           Software," or the equivalent.  When vendor catalogs or advertise-
           ments carry both Shareware and PD programs, the Shareware
           programs must be differentiated from the public domain programs
           in some way (in the description, with an asterisk, by listing the
           registration fee, etc.).

                                                                             10

ADVENTURE GAME TOOLKIT PRODUCT/TECHNICAL SUPPORT


Softworks will make every reasonable effort to fix AGT bugs, and help
registered users by answering technical and other AGT related questions. 
This Product/Technical support for AGT is available to registered users
(only) in several forms:

      (1)  By leaving a message in the 'Softworks' forum on BIX (the BYTE
           Information Exchange).

      (2)  By telephone to David Malmberg at Softworks, Monday through
           Thursday from 7:00 PM to 9:00 PM (Pacific Coast Time) at (510)
           659-0533.  Please respect these hours!!!

      (3)  By CompuServe E-Mail to David Malmberg, CompuServe ID 73435,1277.

      (4)  By GEnie E-Mail to D.MALMBERG.

      (5)  By letter to:   Softworks
                           43064 Via Moraga
                           Mission San Jose, California
                                           94539

           If you send disks or listings that you wish returned, be sure to
           enclosed a self-addressed, stamped envelope (SASE) with
           sufficient postage.  If you do not enclose a SASE, your material
           will not be returned.

Regardless of the method you use to solicit AGT support, if you are having
a problem and you can not get AGT to do what you think it should do, please
provide background information on the following:

      (1)  The version of AGT you are using.  The version number is
           displayed on the title screen whenever you execute COMPILE or
           RUN.

      (2)  The computer system you are using.

      (3)  Your system's configuration, i.e., amount of RAM, number and type
           of disk drives, the type of monitor you are using.

      (4)  Any memory resident programs you have installed at the same time
           you are using AGT and a "rough idea" of what they do and how much
           memory they take.

      (5)  Your problem, i.e., what is happening vs. what you think should
           be happening.

                                                                             11


                                TABLE OF CONTENTS

COPYRIGHT, TRADEMARKS AND WARRANTY . . . . . . . . . . . . . . . . . . . . .  2

QUICK START. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3

ADVENTURE GAME TOOLKIT (AGT) REGISTRATION/ORDER FORM . . . . . . . . . . . .  5

END-USER LICENSE TERMS . . . . . . . . . . . . . . . . . . . . . . . . . . .  7

ADVENTURE GAME TOOLKIT PRODUCT/TECHNICAL SUPPORT . . . . . . . . . . . . .   10

PART 1: INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . .   15
      FEATURES OF THE ADVENTURE GAME TOOLKIT . . . . . . . . . . . . . . .   15
      STRUCTURE OF THIS MANUAL . . . . . . . . . . . . . . . . . . . . . .   17
      HARDWARE REQUIREMENTS FOR AGT. . . . . . . . . . . . . . . . . . . .   17
      QUICK START FOR PLAYING ONE OF THE AGT GAMES * . . . . . . . . . . .   17
      ADVENTURE GAME TOOLKIT FILES . . . . . . . . . . . . . . . . . . . .   19
           FILES NEEDED TO COMPILE AN AGT ADVENTURE. . . . . . . . . . . .   19
           COMPILED OR FINAL VERSION FILES . . . . . . . . . . . . . . . .   20
           SAMPLE AGT ADVENTURE GAME FILES . . . . . . . . . . . . . . . .   21
      HOW TO PLAY THE ADVENTURE GAME(S) PROVIDED WITH AGT. . . . . . . . .   25
           VOCABULARY. . . . . . . . . . . . . . . . . . . . . . . . . . .   25
           STANDARD LEVEL VERBS. . . . . . . . . . . . . . . . . . . . . .   27
           SOME GENERAL COMMENTS ABOUT COMMANDS. . . . . . . . . . . . . .   28
           ABBREVIATIONS AND SPECIAL KEYS. . . . . . . . . . . . . . . . .   28
           SPECIAL WORDS . . . . . . . . . . . . . . . . . . . . . . . . .   29
           NOUNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   30
           NOISE WORDS . . . . . . . . . . . . . . . . . . . . . . . . . .   30
           PREPOSITIONAL PHRASES . . . . . . . . . . . . . . . . . . . . .   30
           COMMAND LINE OPTIONS *  . . . . . . . . . . . . . . . . . . . .   30

PART 2: HOW TO WRITE AN ADVENTURE GAME . . . . . . . . . . . . . . . . . .   32
      INTRODUCTION: WHY SHOULD I WRITE MY OWN ADVENTURE GAME?. . . . . . .   32
      HOW AN AGT ADVENTURE GAME WORKS. . . . . . . . . . . . . . . . . . .   32
           AN OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . . .   32
           STANDARD LEVEL GAME FILES . . . . . . . . . . . . . . . . . . .   34
           TITLE FILES . . . . . . . . . . . . . . . . . . . . . . . . . .   34
           SETTING SCREEN COLORS * . . . . . . . . . . . . . . . . . . . .   35
           INSTRUCTIONS FILES. . . . . . . . . . . . . . . . . . . . . . .   36
           THE WORK-HORSE .DAT FILE. . . . . . . . . . . . . . . . . . . .   36
      ROOMS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   37
           HELP MESSAGES . . . . . . . . . . . . . . . . . . . . . . . . .   39
      NOUNS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   39
           

                                                                             12

      TEXT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   41
           MULTIPLE NOUNS WITH THE SAME NAME . . . . . . . . . . . . . . .   42
           PUSH, PULL, TURN, AND PLAY DESCRIPTIONS . . . . . . . . . . . .   42
           EATING, DRINKING, AND DYING . . . . . . . . . . . . . . . . . .   43
           WEIGHT AND SIZE . . . . . . . . . . . . . . . . . . . . . . . .   44
           LIGHT AND DARKNESS. . . . . . . . . . . . . . . . . . . . . . .   44
      CREATURES. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   44
           GROUPS OF CREATURES . . . . . . . . . . . . . . . . . . . . . .   47
      SPECIALS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   47
           "SPECIAL" SPECIALS. . . . . . . . . . . . . . . . . . . . . . .   48
      CREATING A TYPICAL ROOM. . . . . . . . . . . . . . . . . . . . . . .   50
      "INVISIBLE" NOUNS. . . . . . . . . . . . . . . . . . . . . . . . . .   53
      SCORING. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   55
      OTHER DATA ITEMS IN THE .DAT FILE. . . . . . . . . . . . . . . . . .   55
           INTRODUCTION or INTRO TEXT. . . . . . . . . . . . . . . . . . .   55
           STARTING ROOM . . . . . . . . . . . . . . . . . . . . . . . . .   56
           RESURRECTION_ROOM . . . . . . . . . . . . . . . . . . . . . . .   56
           MAX_LIVES . . . . . . . . . . . . . . . . . . . . . . . . . . .   56
           TREASURE ROOM . . . . . . . . . . . . . . . . . . . . . . . . .   56
           VERB SYNONYMS . . . . . . . . . . . . . . . . . . . . . . . . .   57
                WARNING. . . . . . . . . . . . . . . . . . . . . . . . . .   57
           PLAYER_DEAD . . . . . . . . . . . . . . . . . . . . . . . . . .   57
           GAME_WIN. . . . . . . . . . . . . . . . . . . . . . . . . . . .   58
           GAME_END. . . . . . . . . . . . . . . . . . . . . . . . . . . .   58
      PAGE PAUSES. . . . . . . . . . . . . . . . . . . . . . . . . . . . .   59
      ORDER OF DEFINITIONS . . . . . . . . . . . . . . . . . . . . . . . .   59
      HOW TO INCLUDE COMMENTS IN YOUR AGT DATA FILES . . . . . . . . . . .   59
      CREATING YOUR SOURCE DATA FILES WITH WORD PROCESSORS . . . . . . . .   61
      CREATING A FINAL COMPILED VERSION. . . . . . . . . . . . . . . . . .   61
      AGTNUM * . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   62

PART 3: USING META-COMMANDS IN PROFESSIONAL LEVEL ADVENTURE GAMES. . . . .   63
      CUSTOM USER-DEFINED VERBS. . . . . . . . . . . . . . . . . . . . . .   63
      MAXIMUM_SCORE. . . . . . . . . . . . . . . . . . . . . . . . . . . .   65
      .MSG -- MESSAGE FILES. . . . . . . . . . . . . . . . . . . . . . . .   65
      A TYPICAL GAME TURN. . . . . . . . . . . . . . . . . . . . . . . . .   66
      INTRODUCTION TO META-COMMANDS. . . . . . . . . . . . . . . . . . . .   70
      THE FORMAT OF META-COMMANDS. . . . . . . . . . . . . . . . . . . . .   70
      META-COMMANDS CONDITIONAL TESTS. . . . . . . . . . . . . . . . . . .   73
           PLAYER CONDITIONS . . . . . . . . . . . . . . . . . . . . . . .   73
           ITEM(S) CONDITIONS. . . . . . . . . . . . . . . . . . . . . . .   74
           NOUN CONDITIONS . . . . . . . . . . . . . . . . . . . . . . . .   75
           MISCELLANEOUS CONDITIONS  . . . . . . . . . . . . . . . . . . .   77
      META-COMMANDS ACTION TOKENS. . . . . . . . . . . . . . . . . . . . .   78
           PLAYER ACTION TOKENS  . . . . . . . . . . . . . . . . . . . . .   78
           A WORD OF WARNING . . . . . . . . . . . . . . . . . . . . . . .   79
           ITEM/NOUN/LOCATION ACTION TOKENS  . . . . . . . . . . . . . . .   79
           MISCELLANEOUS ACTION TOKENS . . . . . . . . . . . . . . . . . .   81
      SPECIAL META-COMMAND SITUATIONS. . . . . . . . . . . . . . . . . . .   82
           FLAGS . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   82
           DEBUG FLAG. . . . . . . . . . . . . . . . . . . . . . . . . . .   83
           COUNTERS. . . . . . . . . . . . . . . . . . . . . . . . . . . .   83

                                                                             13

           VARIABLES . . . . . . . . . . . . . . . . . . . . . . . . . . .   83
           NUMBER INPUT. . . . . . . . . . . . . . . . . . . . . . . . . .   85
           ASKING AND ANSWERING QUESTIONS. . . . . . . . . . . . . . . . .   86
           DEALING WITH MULTIPLE NOUNS WITH THE SAME NAME. . . . . . . . .   87
           HANDLING THE CONTENTS OF VARIOUS THINGS . . . . . . . . . . . .   88
           OPENING AND CLOSING PASSAGEWAYS BETWEEN ROOMS . . . . . . . . .   89
      META-COMMAND REDIRECTION . . . . . . . . . . . . . . . . . . . . . .   90
      ORGANIZATION OF THE .CMD FILE. . . . . . . . . . . . . . . . . . . .   91
      AGTNUM AND META-COMMANDS * . . . . . . . . . . . . . . . . . . . . .   95

PART 4:  SAMPLE AGT META-COMMAND SCENARIOS . . . . . . . . . . . . . . . .   96
      SCENARIO 1: "FIND" VERB ACTIONS. . . . . . . . . . . . . . . . . . .   96
      SCENARIO 2: RANDOM ACTIVITIES BY GUARD . . . . . . . . . . . . . . .   98
      SCENARIO 3: INTERACTION WITH OTHER CHARACTERS. . . . . . . . . . . .  105

PART 5:  "DEBUGGING" YOUR ADVENTURE. . . . . . . . . . . . . . . . . . . .  114

APPENDIX A:  AGT STANDARD LEVEL VERBS. . . . . . . . . . . . . . . . . . .  115

APPENDIX B:  META-COMMANDS CONDITIONAL TESTS . . . . . . . . . . . . . . .  117
      PLAYER CONDITIONS. . . . . . . . . . . . . . . . . . . . . . . . . .  117
      ITEM(S) CONDITIONS . . . . . . . . . . . . . . . . . . . . . . . . .  118
      NOUN CONDITIONS  . . . . . . . . . . . . . . . . . . . . . . . . . .  119
      MISCELLANEOUS CONDITIONS . . . . . . . . . . . . . . . . . . . . . .  120

APPENDIX C:  META-COMMANDS ACTION TOKENS . . . . . . . . . . . . . . . . .  121
      PLAYER ACTION TOKENS . . . . . . . . . . . . . . . . . . . . . . . .  121
      ITEM/NOUN/LOCATION ACTION TOKENS . . . . . . . . . . . . . . . . . .  122
      MISCELLANEOUS ACTION TOKENS  . . . . . . . . . . . . . . . . . . . .  123

APPENDIX D:  AGT ERROR MESSAGES. . . . . . . . . . . . . . . . . . . . . .  125
      ERRORS DURING GAME COMPILATION . . . . . . . . . . . . . . . . . . .  125
      ERRORS DURING RESTORING GAME . . . . . . . . . . . . . . . . . . . .  125
      ERRORS DURING GAME PLAY. . . . . . . . . . . . . . . . . . . . . . .  125
      TURBO PASCAL RUN-TIME ERRORS . . . . . . . . . . . . . . . . . . . .  126

APPENDIX E: VALUE RANGES FOR GAME DEFINITIONS. . . . . . . . . . . . . . .  127

APPENDIX F: MACINTOSH AND ATARI ST DIFFERENCES . . . . . . . . . . . . . .  128
      MACINTOSH DIFFERENCES. . . . . . . . . . . . . . . . . . . . . . . .  128
           HARDWARE REQUIREMENTS . . . . . . . . . . . . . . . . . . . . .  128
           AGT FILES AND FILE NAMES. . . . . . . . . . . . . . . . . . . .  128
           QUICK START AT PLAYING ONE OF THE GAMES . . . . . . . . . . . .  128
           OPTION AND COMMAND/APPLE KEYS . . . . . . . . . . . . . . . . .  129
           COMMAND LINE OPTIONS. . . . . . . . . . . . . . . . . . . . . .  129
           SCREEN COLORS . . . . . . . . . . . . . . . . . . . . . . . . .  130
           CREATING YOUR SOURCE DATA FILES . . . . . . . . . . . . . . . .  130
           AGT UTILITY PROGRAMS. . . . . . . . . . . . . . . . . . . . . .  130
      ATARI ST DIFFERENCES . . . . . . . . . . . . . . . . . . . . . . . .  131
           HARDWARE REQUIREMENTS . . . . . . . . . . . . . . . . . . . . .  131
           AGT FILES AND FILE NAMES. . . . . . . . . . . . . . . . . . . .  131

                                                                             14

           FUNCTION AND KEY PAD KEYS . . . . . . . . . . . . . . . . . . .  131
           COMMAND LINE OPTIONS. . . . . . . . . . . . . . . . . . . . . .  131
           CREATING YOUR SOURCE DATA FILES . . . . . . . . . . . . . . . .  132
           AGT UTILITY PROGRAMS. . . . . . . . . . . . . . . . . . . . . .  132

APPENDIX G: ANNUAL AGT CONTEST . . . . . . . . . . . . . . . . . . . . . .  133

APPENDIX H: AGT UTILITY DISK FOR IBM . . . . . . . . . . . . . . . . . . .  135

Appendix I: ABOUT THE AUTHORS. . . . . . . . . . . . . . . . . . . . . . .  138


NOTE: Sections above marked with an asterisk denote topics where there are
differences among the Macintosh, Atari ST and IBM AGT versions as explained
in Appendix F.


                                                                             15

PART 1: INTRODUCTION


The Adventure Game Toolkit is designed to allow you to create and play your
own text adventure games.  Once created, your adventure games can be shared
with and enjoyed by others -- even if they do not have a copy of the
Adventure Game Toolkit themselves.

The Adventure Game Toolkit (AGT) began life as a program by Mark Welch
called the Generic Adventure Game System (GAGS).  Using GAGS it was
possible for the non-programmer to develop complete adventure games using a
fixed (but relatively large) vocabulary of action verbs.  David Malmberg
took GAGS and made a number of enhancements including the ability to
customize the vocabulary and to program complex conditional tests and a
rich assortment of actions and messages using a special meta-language
(designed specifically for adventure games).  The current Adventure Game
Toolkit combines the best features of both approaches to enable the user to
create two distinct levels of adventure games:

      (1)  Standard Level games that require no programming experience
           (honestly!), only a fertile imagination.  These Standard Level
           games follow the original GAGS format and only require that the
           user generate the game using a word processor or text editor to
           describe the various locations, objects and results of actions
           that collectively make up the game.

      (2)  Professional Level games that also make use of the special
           adventure game meta-language to create games as complex and rich
           as the game designer's imagination and prose style will allow. 
           These games should be technically comparable with the published
           text adventure games from firms like Infocom.


FEATURES OF THE ADVENTURE GAME TOOLKIT

AGT has a number of features that make it a very comprehensive adventure
product.  These features make AGT more powerful, more professional and
easier to use than any previously available Adventure Game development
system.  Some of these key features are:

      POWERFUL

           *    Big, complex games with up to 200 locations, 100 inanimate
                objects (e.g., treasures, swords, lakes, trees, books, etc.)
                and 100 animate objects (e.g., people, animals or
                creatures).

           *    Large standard vocabulary with potential to define many more
                words unique to a specific adventure.  Typical games can
                have a vocabulary of 500 words or more.

                                                                              16

          *     Sophisticated parser that can understand (1) complex input
                commands including pronouns (IT, HIM, HER, THEM, MY and
                ITS), and (2) compound commands separated by AND or THEN or
                punctuation symbols, and (3) commands addressed to
                characters within the game.  Here are a few examples of
                commands AGT can handle with ease:

                      GET THE FLASH LIGHT AND THEN SWITCH IT ON
                      DROP THE FOOD, THE KEY AND THE BOTTLE THEN UNLOCK THE
                      DOOR
                         WITH THE BRASS KEY AND THEN LEAVE
                      PUT ON THE CLOAK, THEN EXAMINE IT; READ ITS LABEL
                      PLACE THE GREEN ROCK AND THE SMALL PEBBLE BEHIND THE
                      TREE
                      ENTER THE HOUSE; GET ALL; EXIT; SOUTH; SOUTH THEN DOWN
                      SULU, SET A COURSE FOR ALPHA 14
                      SCOTTY, BEAM DOWN A TRICORDER AND THE QWERTY MODULE

           *    Special, English-like meta-language (especially developed for
                writing Adventure games) that gives the game designer total
                control and flexibility in the development of his/her games.

           *    Source code available to Registered Users.  Over 13,000 lines
                of Turbo Pascal 4.0/5.0/5.5/6.0 that may be customized to fit
                the game designer's unique needs.  Other Pascal versions
                available for the Macintosh and Atari ST.  Amiga version is
                written in Modula-2.

      PROFESSIONAL

           *    "Look and feel" of Infocom adventure games with similar screen
                layout and standard vocabulary and routines.

           *    Automatic screen adaptation to use either a color or a mono-
                chrome monitor.  Color combinations may be specified by the
                game designer or by the player during the game.

           *    Predefined function and cursor keys to input frequently used
                commands and move directions.

           *    SCRIPT and UNSCRIPT commands to echo game output to printer.

      EASY-TO-USE

           *    Large library of completed games that can be enjoyed simply as
                great entertainment or used as a platform by the game designer
                to build upon and/or learn from.

           *    Professionally written documentation totalling over 200 pages. 
                Has numerous examples that unveil the "secrets" of great
                adventure writers.


                                                                              17

STRUCTURE OF THIS MANUAL

PART 1 (the section you are reading) gives an overview of the Adventure
Game Toolkit, the various files on the disk(s), and explains how to play
the adventure games created by the AGT.

PART 2 gives a number of pointers on how to create a good adventure game. 
It also explains the way AGT defines an adventure game in terms of files
and game data elements like Rooms, Nouns, and Creatures and gives several
examples of each.

PART 3 explains the use of AGT's unique meta-language and how it can be
used to create Professional Level adventure games.  Numerous examples are
given.

PART 4 gives several scenarios where meta-language commands have been used
to create typical adventure games situations, like random attacks by other
characters, and how to expand the game's vocabulary to include new verbs
and actions.

PART 5 gives a number of helpful "secret" commands for "debugging" your
game once you have a first draft.

The final part of the manual is a series of Appendices that give detailed
information on a number of specific AGT topics for easy reference.


HARDWARE REQUIREMENTS FOR AGT

The games created by the Adventure Game Toolkit requires an IBM-compatible
computer with at least 384K of memory, MS-DOS 2.1, and at least one disk
drive.  You may use any kind of monitor and AGT will automatically adjust
its output to best suit your monitor.


QUICK START FOR PLAYING ONE OF THE AGT GAMES

If you've never played an adventure game before, the best way to start to
understand how an adventure game works is to play one.  Before you can do
that, however, there are a few things you should do first to protect your
disk(s) and to create the final version of the game from the source files
on the disk(s).

Let's make a playable copy of CRUSADE.

                                                                             18

1.    First, make a copy of the original disk(s) and put them in a safe
      place.  That way, if you accidentally damage the disk(s) you're
      playing with, you can still re-copy the original(s).  Check your DOS
      manual for the correct form of the COPY or DISKCOPY command that is
      appropriate for your particular system.

2.    If there is a file on the disk(s) called READ.ME or README.AGT, read
      that file before going further.  These files will have information on
      changes and/or features that have been made after the documentation
      was created.

3.    Copy the following files to a new, formatted disk:
           COMPILE.EXE
           CRUSADE.DAT
           CRUSADE.CMD
           CRUSADE.MSG

These are the "source" files for the CRUSADE adventure.  Put this disk in the
A: drive and make that drive the default drive by entering "A:<RETURN>". 
Then enter "COMPILE CRUSADE<RETURN>".  AGT will then take 3 to 5 minutes to
produce a finished version of the CRUSADE adventure on the same disk, by
creating the following new files:
           CRUSADE.D$$
           CRUSADE.DA1
           CRUSADE.DA2
           CRUSADE.DA3
           CRUSADE.DA4
           CRUSADE.DA5

These are the "compiled" or final files for CRUSADE that AGT has created.

4.  Next, copy the following files to a new (different) formatted disk:
           RUN.EXE
           CRUSADE.TTL
           CRUSADE.INS
           CRUSADE.BAT
           CRUSADE.D$$
           CRUSADE.DA1
           CRUSADE.DA2
           CRUSADE.DA3
           CRUSADE.DA4
           CRUSADE.DA5
           ORDERFRM.AGT

Then type "CRUSADE<RETURN>" at the DOS prompt to play the finished version of
the CRUSADE adventure created by AGT.


                                                                             19

ADVENTURE GAME TOOLKIT FILES


FILES NEEDED TO COMPILE AN AGT ADVENTURE

Included on the disk(s) are numerous files.  If there is a file on the
disk(s) called READ.ME or README.AGT, read that file before going further.

In order to compile or create a finished adventure from your source files,
you will need to put the following files on a new, formatted disk:

      COMPILE.EXE     The file COMPILE.EXE is the AGT program that converts
                      your AGT "source" files into the "compiled" or final
                      files needed to play the adventure.

      *.DAT           e.g., CRUSADE.DAT.  Files with the extension (suffix)
                      .DAT are source data files read by the COMPILE.EXE
                      program when it is running.

      *.CMD           e.g., CRUSADE.CMD.  Each file with the extension .CMD
                      is a source data file containing a set of special meta-
                      language commands for a corresponding game in a .DAT
                      file.  The use of a *.CMD file is unique to
                      Professional Level adventure games.  Games that do not
                      use these Professional Level features (such as, the
                      original GAGS games) would not have a *.CMD file.

      *.MSG           e.g., CRUSADE.MSG.  Each file with the extension .MSG
                      is a source data file containing a set of special
                      messages for a corresponding game in a .DAT file.  The
                      use of a *.MSG file is unique to Professional Level
                      adventure games.  Games that do not use these Profes-
                      sional Level features (such as, the original GAGS
                      games) would not have a *.MSG file.

After these are on a new, formatted disk, you should enter the command
"COMPILE GameName", e.g., "COMPILE CRUSADE".  After a few minutes, AGT will
pause and give you a message about how much space there is on your disk
compared to how much space you need for the "final" or "compiled" version
files.  If you don't have enough space, the program will suggest you put in
a clean (already formatted) disk, before it writes the final files.


                                                                             20

COMPILED OR FINAL VERSION FILES

After the game has been compiled, you can create a final, playable disk for
the game.  This disk will have the following files:

      RUN.EXE   This is the program "engine" that runs your compiled adven-
                ture game.  RUN.EXE must be on the disk in order to play any
                compiled, final AGT game.  All of the information that is
                unique to the adventure will be contained in compiled data
                files, described below:

      *.BAT     e.g., CRUSADE.BAT.  Each file with the extension .BAT is
                used to start the final version of the game, i.e., it
                contains the DOS batch instruction "RUN GameName", e.g.,
                "RUN CRUSADE".  *.BAT files are optional.

      *.TTL     e.g., CRUSADE.TTL.  Each file with the extension .TTL
                contains the title file for a corresponding game file.
                (*.TTL files are optional)

      *.INS     e.g., CRUSADE.INS.  Each file with the extension .INS con-
                tains a set of instructions for a corresponding game. (*.INS
                files are optional)  If the game disk contains a *.INS file
                (i.e., CRUSADE.INS), the game will ask the player "Do you
                wish to see the instructions?"  If the player answers with a
                YES or Y, the instruction file will be displayed.  If the
                game disk does not contain a *.INS file, play begins
                normally at the starting location.

      *.D$$     e.g., CRUSADE.D$$.  Each file with the extension .D$$
                contains all the encrypted messages for the game.  *.D$$
                files are NOT optional.

      *.DA1     e.g., CRUSADE.DA1.  Each file with the extension .DA1
                contains general data about the game.  *.DA1 files are NOT
                optional.

      *.DA2     e.g., CRUSADE.DA2.  Each file with the extension .DA2
                contains encrypted data about the ROOMS in the game.  *.DA2
                files are NOT optional.

      *.DA3     e.g., CRUSADE.DA3.  Each file with the extension .DA3
                contains encrypted data about the NOUNS in the game.  *.DA3
                files are NOT optional.

      *.DA4     e.g., CRUSADE.DA4.  Each file with the extension .DA4
                contains encrypted data about the CREATURES in the game. 
                *.DA4 files are NOT optional if you have CREATURES in the
                game.  If there are no CREATURES, then no *.DA4 file will be

                                                                             21

                created.

      *.DA5     e.g., CRUSADE.DA5.  Each file with the extension .DA5
                contains encrypted meta-language commands for the game. 
                *.DA5 files are NOT optional if you have meta-language
                commands in the game.  If there are no meta-language
                commands, then no *.DA5 file will be created.

The final or compiled files of an adventure game take up less disk space
than the source files and are encrypted.  These files are not only safe
from "peeking" and "prying" eyes, but have the advantage of loading very
fast.  Even the largest AGT game will load in about 15 seconds -- just long
enough to read the title screen.


SAMPLE AGT ADVENTURE GAME FILES

There are a number of complete adventure games that have been developed
using AGT and its special meta-language.  The reader is encouraged to study
these games for examples of how AGT can be used to accomplish a wide
variety of Professional Level adventure game tasks and tricks.  These
Professional Level games include:

      CAVE      An AGT version of the original Crowther and Woods "Colossal
                Cave" Adventure Game.

      CRUSADE   Rescue the princess from the evil Baron's dungeon.

      QUEST     Recover your magic spells and amulets from Blackwing's Pit.

      SQUYNCH   Challenge the evils and mysteries of the Land of Squynch. 
                Very clever!  As good as Infocom!

      PARANOIA  An adaptation of a classic fantasy role-playing game from
                "SpaceGamer/FantasyGamer" magazine.

      BIGDATE   Get ready for your big date.  An adventure told from a wom-
                an's point of view.

      ELF       Help Santa make it a merry, merry Christmas by discovering
                how to make Rudolph's nose shine bright enough to fly the
                sleigh through the fog covering the North Pole.

In addition there are a number of Standard Level games that could have been
created totally without any programming knowledge or experience:

      UNDERGND  A game of survival after World War III.  Uses all of the
                tricks of the original GAGS (Standard Level) adventures.

      ALICE     An adventure using the characters from Alice In Wonderland. 
                This game was the winning entry in the first annual GAGS
                game writing contest. (By Doug Asherman.)

                                                                             22

      DEENA     A woman warrior's struggle to escape from the lecherous
                Gendi tribe.  (R-rated) (By Ev Cheney)

      DRAGONS   An adventure in the Sultan's palace with side trips to his
                dungeon, the torture chamber and the harem.  (R-rated)

      FABLE     An allegorical quest for meaning and understanding in life.

      GHOSTTWN  Find and rescue the rancher's daughter from the mysterious
                ghost town.  (R-rated)

      LOTTERY   An adventure in San Francisco with emphasize on the "red
                light" district.  (R-rated)

      CTA       An allegorical adventure where you battle figures like
                "Unbelief", "Greed" and "Lust" using such weapons as the
                "Sword of the Spirit" and the "Staff of Righteousness".

      LASAR     Seek out and destroy the threats to peace and prosperity in 
                the Kingdom of Ellasal.

      STJOSEPH  Solve the mystery of the town of Old St. Joseph, Florida.

      EIGHTY    A geography game based on "Around the World in Eighty Days". 
                Used to teach English as a second language.

      VANPELT   An orientation to the Van Pelt library at the University of
                Pennsylvania.  Used to teach new students how to find their
                way around the library and how to undertake basic library
                research.

Many of the above games are included on the basic AGT set of disks or can
be downloaded from various BBSs and timesharing services that maintain AGT
files.  If you are unable to find one or more of the above games that you
think you might enjoy, any of these games can be ordered from Softworks for
$6 each.

In addition, Softworks sponsors an annual Adventure Game writing contest
and makes the AGT source code available for the winning games.  The 1988
winners included:

      A DUDLEY DILEMMA -- By Lane Barrow.  In this game, you play the role
      of a Harvard University student living in Dudley House in his/her
      quest for knowledge, adventure and a diploma.  This game was the first
      prize winner in the 1988 contest.  This game is a very clever,
      humorous and challenging adventure in the classic style of Infocom.

      DES RING DES NIBELUNGEN -- By Michael R. Harris.  You play the role of
      Siegfried in an adventure based on the operas of Richard Wagner --
      complete with a very tender and loving Brunnhilde.  A very unusual
      approach to an adventure game.

                                                                             23

      STAR PORTAL -- By Michael Detlefsen.  A science fiction adventure
      based on a Damon Knight short story, "Ticket to Anywhere", in which
      you journey to the stars in search of adventure, encounter alien crea-
      tures, explore the ruins of deserted cities, and acquire a pet dog. 
      An awesome game!

      SUSAN, A LUSTFUL GAME -- By Bill Larkins.  You attempt to score points
      with your girlfriend, Susan.  An R-rated game for adults only.

      TAMORET -- By Michael J. Lyons.  You are called upon to help return a
      creature from the fourth dimension that has escaped into our world. 
      The largest and most complex game every created with AGT (so far).

      TARK, PRIESTESS OF THE FIRST CHURCH, IN HER BATTLE AGAINST THE DEMON
      OF DARK DESIRE -- By Philip Kegelmeyer.  An extremely well written
      game based on a "Dungeons and Dragons" theme (complete with spells and
      hit points) where you play a priestess struggling against the forces
      of evil.

All of the above winning games are available from Softworks, the publisher
of the Adventure Game Toolkit, in a special 2-disk set of files called "The
Best of the Contest - 1988".  These disks contain over a mega-byte of AGT
source code.  These disks are available for only $12.  The $12 cost covers
both disks and includes all of the winning games.

As a special "bonus" these disks also contain the AGT source code to these
recent adventure games:

      PORK -- By David Malmberg.  A parody of the Infocom game of ZORK.  If
      you were ever frustrated by ZORK, playing this game is your chance to
      enjoy the sweet fruits of revenge.

      LOVE'S FIERY RAPTURE -- By Natasha Mirage.  A torrid tale of what
      could turn out to be THE perfect date.  A parody (???) of romance
      novels like those published by Harlequin.  This game demonstrates a
      very clever way to translate a "Choose Your Own Adventure" style game
      into an AGT game.

In addition, Softworks also offers the source code for the 1989 contest
winners on a 2-disk set -- also for only $12 for both disks.  These disks
include  the following games:

      SON OF STAGEFRIGHT -- By Mike McCauley.  In this game, you play the
      role of an actor (or actress) trying to get out of an old, abandoned
      theater.  This is an adventure game in three "Acts", where each Act
      has a different theme and a different challenge.  This game was the
      first prize winner in the 1989 contest.  This award winning adventure
      is fun(ny), frightening and very clever.

      EASTER EGG HUNT -- By Tom and Ginnie Reynolds.  A game aimed at and
      suitable for children ages 7-12.  It contains no killing, monsters, or
      anything scary.  Easy for adults but challenging for children.  This

                                                                             24

      is a very special and delightful game!

      FAST LANE -- By Richard Baribault.  In this game you attempt, against
      much adversity, to find, enter, and win a Classic Car Show.  You must
      overcome obstructive family members, odd creatures, criminals
      (including "Big Bubba"), the law, and other assorted trials and
      difficulties.  A very well done game with an usual theme.

      HOUSE OF THE O's -- By Wally O. and Pete D.  This game is unique among
      adventure games -- it has no dragons or spaceships, no magic potions
      or trapdoors.  The game is based on the ordinary activities of an
      ordinary family living in an ordinary house in Mosquito Heights, New
      Jersey.  A game filled with subtle humor.

      PORK II -- THE GIZZARD OF SHOWBIZ -- By Bill Larkins.  This game is a
      parody of Infocom's ZORK II.  The game features a LEWD mode (not
      recommended for youngsters) as well as a TAME mode.  A test must be
      passed to get in the LEWD mode.  If you enjoyed PORK I, you should
      welcome this clever sequel.

      PYRAMID OF MUNA -- By Alfred W. King II.  In this game, the player
      explores an ancient Mexican pyramid and attempts to discover its
      metaphysical secrets.  An adventure based on the "Elements of the
      Cosmology of The Builders".  An exotic implementation of a classic
      adventure theme.

      QUEST FOR THE HOLY GRAIL -- By Mike Detlefsen.  A zany, madcap
      adventure, loosely (very loosely) based on the movie "Monty Python and
      the Holy Grail".  If you liked the movie and/or enjoy the comedy of
      Monty Python, you will love this game.

      SIR RAMIC HOBBS AND THE HIGH LEVEL GORILLA -- By Gil Williamson.  The
      adventures of a Knight Errant and his faithful companion, the Wizard
      Prang, as they seek to rescue a beautiful Princess from a fiendish
      villain's evil grasp.  Reminiscent of Don Quixote, wryly retold with a
      delightfully British sense of humo(u)r.

      THE BATTLE OF PHILIP AGAINST THE FORCES OF CREATION -- By Peter Arnold
      and Anne Ungar.  This game is based on a "Dungeons and Dragons" theme. 
      The game was written as a continuation of and a response to TARK, one
      of the winning games from the 1988 contest.  A very well written
      adventure. Especially enjoyable if you are a "DnD" fan.

      THE PILOT -- OR A FLIGHT INTO FANTASY -- By A. G. Jackson.  This game
      is action-packed from its opening scene that has you trying to escape
      from a jet that is hurtling towards the ground at Mach 2 to the game's
      final scenes where you are exploring a mysterious cave beneath the
      polar ice cap.

If you wish to order the source code for these games from Softworks, be
sure to specify that you want the special 2-disk set of files called "The
Best of the Contest - 1989".

                                                                             25

Incidently, see Appendix G on page 133 for details on how you can enter
your game in the current AGT game writing contest.


HOW TO PLAY THE ADVENTURE GAME(S) PROVIDED WITH AGT


VOCABULARY

The Adventure Game Toolkit creates adventure games that understand a wide
variety of commands.  A typical AGT game might have a vocabulary totalling
500 words or more.

Your game's commands should generally be in the format:

   <verb phrase> <(multiple) noun phrase(s)> <preposition> <noun phrase/object>

Verb phrases can consist of a simple verb like EAT, SHOOT, READ or a verb
followed by a preposition such as CLIMB UP, JUMP THROUGH, or SWIM IN.  Noun
(or object) phrases can consist of a single word noun like TREE, ROCK, LAKE
or a noun and its adjective such as RED ROCK, SMALL BOWL or UGLY MUTANT. 
Several nouns may be connected with AND's or commas.  Articles like A, AN
or THE are optional.  The personal pronouns MY and ITS are also optional. 
The pronouns IT, THEM, HIM and HER may be used to refer to a previously
mentioned noun.

Here are some (hypothetical) examples of valid commands:

           PLACE A RED ROCK IN THE SMALL BOWL
           PUT THE GREEN ROCK AND THE SMALL PEBBLE BEHIND THE OAK TREE
           READ MY POETRY BOOK
           SWIM IN THE SWIMMING POOL
           EXAMINE THE GOLD RING, THE DWARF AND THE SILVER NECKLACE
           EAT THE CELERY, THE TUNA, THE APPLE AND THE ONION
           THROW THE BATTLE AXE AND THE LARGE ROCK AT THE WEREWOLF
           SHOOT THE BURGLAR WITH THE REVOLVER
           ATTACK HIM
             ("HIM" will refer to last noun mentioned, e.g., the burglar)
           FIRE THE LASER PISTOL AT THE ALIEN MUTANT
           GET THE BOOK (also: TAKE THE BOOK)
           READ IT
             ("IT" will refer to last noun mentioned, e.g., the book)
           GET ALL (will get everything movable at the current location)
           GET THE KEYS, BOTTLE, FOOD AND THE CLOAK
           EXAMINE THE KEYS, BOTTLE, FOOD AND CLOAK
           PUSH THE RED BUTTON AND THE GREEN BUTTON
           UNLOCK THE FILE CABINET WITH THE STEEL KEY
           JUMP THROUGH THE OPENING
           JUMP OVER THE LOG
           NORTH
           SOUTHWEST

                                                                             26

           PLACE AN AXE AND THE SHIELD NEXT TO THE BIG TREE
           PUT THE FOOD ON THE KITCHEN TABLE
           TURN ON THE FLASHLIGHT
           LIGHT THE TORCH WITH THE WOODEN MATCHES
           SCREAM AT THE UGLY TROLL
           CLIMB UP THE LADDER
           EXTINGUISH THE FIRE (or PUT OUT THE FIRE)
           DRINK THE WHITE WINE
           THROW THE FIRE WOOD IN THE STOVE
           PULL THE BELL CORD
           WEAR THE STUPID HAT (also: PUT ON THE STUPID HAT)
           TAKE OFF THE HAT (also: REMOVE THE HAT)
           NE (for NORTHEAST)
           DROP THE KEY AND THE BOTTLE
           ENTER THE CAVE
           XYZZY (i.e., a "magic" word)
           TURN THE DOORKNOB
           PLAY WITH THE DOG
           TALK TO (or TALK WITH) THE OLD MAN (ABOUT THE WEATHER)
           TELL JEFF ABOUT THE SWORD
           ASK JODIE ABOUT THE CRIME

Compound commands can be created by connecting single commands (like those
above) with "AND", "THEN" or the punctuation symbols "," or ";" to connect
two or more separate commands.  However, "end-of-sentence" punctuation
symbols like ".", "!" and "?" should not be used.  Below are a few examples
of valid compound commands:

           TURN THE DOORKNOB; OPEN THE DOOR THEN ENTER THE ROOM
           CLIMB DOWN THE LADDER THEN SOUTH, WEST AND NORTHWEST
           GET THE CLOAK AND THEN EXAMINE IT; READ THE LABEL
           DROP THE FOOD AND THE BOTTLE THEN UNLOCK THE DOOR AND THEN LEAVE
           GET THE TORCH, LIGHT IT WITH THE WOODEN MATCHES THEN EXAMINE IT

AGT's parser also allows you to give commands to other characters in the
game like these:

           SULU, SET A COURSE FOR ALPHA 14
           SCOTTY, BEAM DOWN A TRICORDER AND THE QWERTY MODULE
           HELMSMAN, RAISE THE DEFLECTOR SHIELDS
           BONES, COME TO THE BRIDGE

The comma after the character's name is optional.

One point of advice about command structure is in order.  Your commands
should be structured to follow the most "natural" sequence of words when
two or more sequences are possible.  For example, THROW THE GOLDEN EGGS TO
THE TROLL will be understood by the AGT parser, whereas THROW TROLL THE
EGGS will not be understood -- even though it is understandable to most
humans as equivalent.  Similarly, you should avoid the verb "USE", such as
USE THE KEY TO UNLOCK THE DOOR.  This command should be entered simply as
UNLOCK THE DOOR WITH THE KEY.

                                                                             27

NOTE:  Player's input commands will be shown in all caps throughout this
document.


STANDARD LEVEL VERBS

Standard level games have a fixed set of verbs -- although these may all be
supplemented by additional synonyms.  Professional level games have all of
the standard level verbs plus they can have additional verbs that are
defined uniquely for each game.  The standard level verbs and the form of
their commands are shown below:

Meanings of notation:
      [required word]
      {optional word}
      | (means OR, i.e., alternative words)

      Verbs that do not require nouns
      ===============================
            N,S,E,W,NE,NW,SE,SW,U,D,
            NORTH,SOUTH,EAST,WEST,NORTHEAST,NORTHWEST,SOUTHEAST,             
              SOUTHWEST,UP,DOWN
            ENTER | GO [IN | INTO]
            EXIT | LEAVE  (* directions *)

            SCORE  (* display score and status *)
            QUIT | Q  (* end game *)
            INVENTORY | I  (* list things player is carrying and wearing *)
            SCREAM | SHOUT | YELL  (* make noise *)
            WAIT  (* waste a turn *)
            BRIEF | VERBOSE  (* change description mode *)
            L | LOOK  (* repeat full description *)
            SAVE | RESTORE {GAME}  (* save and restore game status *)
            HELP | H  (* ask for help *)
            AGAIN | G (* repeat last command entered *)
            SCRIPT  (* echo all output to both printer (LP1:) and screen *)
            UNSCRIPT  (* send all output to screen only *)

      Verbs that require nouns (and perhaps objects)
      ==============================================
            LIST | SHOW [EXITS]  (* list visible exits *)
            THROW | CAST | DUMP [noun]
               {[AT | TO | IN | INTO | ACROSS | INSIDE] [noun]}
            ATTACK | KILL | FIGHT | HIT [creature] {[WITH] [noun]}
            DROP | PUT DOWN [noun | ALL]
            GET | TAKE | PICK UP [noun | ALL]
            OPEN [noun] {[WITH] [noun]}
            CLOSE | SHUT [noun]
            LOCK [noun] {[WITH] [noun]}
            UNLOCK [noun] {[WITH] [noun]}
            EXAMINE | CHECK | INSPECT | LOOK AT | LOOK IN [noun]
            READ [noun]

                                                                             28

            EAT [noun]
            DRINK [noun]
            PUT | PLACE [noun]
               [IN | WITH | INSIDE | INTO | NEAR | BEHIND |
                BESIDE | ON | UNDER] [noun]
            PUSH | TOUCH [noun] {[WITH] [noun]}
            TURN [noun] {ON | OFF}
            TURN {ON | OFF} [noun]
            PULL [noun]
            PLAY {WITH} [noun]
            LIGHT [noun]
            EXTINGUISH | PUT OUT [noun]  (* synonym is "EXT" *)
            SHOOT | FIRE [noun] [AT] [creature]
            SHOOT | FIRE [creature] [WITH] [noun]
            PUT ON | WEAR [noun | ALL]
            TAKE OFF | REMOVE [noun | ALL]
            ASK [creature] [ABOUT] [noun]
            TALK [TO | WITH] [creature] {[ABOUT] [noun]}
            TELL [creature] [ABOUT] [noun]


SOME GENERAL COMMENTS ABOUT COMMANDS

Figuring out what words work in a game is part of the "challenge" of some
adventure games.  The usual directions are understood by AGT games (N, S,
E, W, NE, NW, SE, SW, UP, and DOWN; in some cases, ENTER or EXIT might also
be appropriate).  Other events might also cause you to change location: if
you detonate a nuclear warhead, for example, you'll likely be immediately
transported somewhere far, far away.

You can try to TAKE or GET most things that are in a room with you; you
should EXAMINE or LOOK AT most visible nouns as well, whether or not you
are carrying them.  You can DROP or THROW anything you're carrying.  Eating
and drinking are often permitted, but eating strange things is usually
dangerous.  If something seems to be closed or locked, you can try to open
or unlock it -- but it may require some special kind of key.

There's no penalty for incorrect words: if the game doesn't understand a
word, it gives you another chance and doesn't count the invalid input as a
turn.

If you try to do something foolish like EAT THE CHAIR or GET THE BUILDING,
the game will give you an appropriate response like "Eat the chair?  You
must be kidding!" or "The building can not be taken".


ABBREVIATIONS AND SPECIAL KEYS

All of the directions can be abbreviated by using one or two key letters.

                                                                             29

For example, N for NORTH, SW for SOUTHWEST, U for UP, etc.  You can also
abbreviate EXAMINE as EX (e.g., EX BOOK).  To turn out a light, you can
EXTINGUISH it, and EXTINGUISH can be abbreviated as EXT (e.g., EXT LAMP). 
Other acceptable abbreviation are L for LOOK, I for INVENTORY, G for AGAIN,
H for HELP and Q for QUIT.

It is also possible to use the function and cursor keys in lieu of many
frequently used commands and directions as follows:

           F1  --  GET                  Up Arrow  --  NORTH
           F2  --  DROP                 Down Arrow  --  SOUTH
           F3  --  EXAMINE              Right Arrow  --  EAST
           F4  --  READ                 Left Arrow  --  WEST
           F5  --  OPEN                 Home  --  NORTHWEST
           F6  --  CLOSE                End  --  SOUTHWEST
           F7  --  INVENTORY            Pg Up  --  NORTHEAST
           F8  --  LOOK                 Pg Dn  --  SOUTHEAST
           F9  --  SCORE                Gray "-" Key -- UP
           F10  --  HELP                Gray "+" Key -- DOWN
                                        Ins -- ENTER
                                        Del -- EXIT

If at any time during the game the player needs to be reminded of what the
function and cursor keys stand for, hitting the ? key followed by <ENTER>
will produce a diagram of what each cursor and function key means.


SPECIAL WORDS

Certain words have special meanings to AGT games.  SCORE will let you see
how much progress you've made and will give you an idea how much of the
game you've seen so far.  QUIT will permit you to stop the game and return
to DOS.  SAVE will allow you to save the current game status, and RESTORE
will restore a previously-saved game.  AGAIN (or its abbreviation G) will
cause the game to respond as if the previous command had been entered
again.

In addition, AGT also allows the use of SCRIPT to echo all of the game's
output to your printer (as well as the screen).  UNSCRIPT may be used to
turn off the printer output.

As you move around through the game, you'll notice that the game provides a
long text description of each room only when you first enter the room.  To
see the full description again, type LOOK or L or hit the F8 function key. 
The game doesn't keep these long text descriptions in memory, but instead
reads them from disk each time it needs them.  If you don't like this
delay, you can suppress the long text by using the BRIEF command.  VERBOSE
will bring them back.

Further, in AGT it is possible to issue commands for HELP or alternatively
hit the F10 key.  Be warned, however, that some game designers might feel
that the situation does not deserve any help or, worse yet, some deviate

                                                                             30

designers might actually give the player a hint that is a little
misleading.


NOUNS

While the list of verbs is generally similar from game to game, all the
nouns change every time.  One game might be filled with weapons and
creatures, while another might contain many keys and locks.  Most nouns are
unique: you probably won't find more than one "gold key," but you might
find a "brass key," an "access card," and an "entry pass."  The game only
understands an adjective if it is correctly followed by the matching noun:
if TAKE RED FLUTE is valid, the game will not try to guess what you meant
by TAKE RED or TAKE RED INSTRUMENT or TAKE THE RED ONE.  It will accept
TAKE FLUTE, but not TAKE BLUE FLUTE.

With some verbs, nouns are optional.  For example, NORTH is quite clear by
itself, and any "valid" words following it will be ignored completely.  EAT
needs a noun of some kind, preferably an edible one.  And some things may
not be possible unless you specify a tool: UNLOCK PADLOCK may not be
acceptable, while UNLOCK THE PADLOCK WITH THE BRASS KEY may work fine.


NOISE WORDS

The words "THE", "MY", "ITS", "A" and "AN" are ignored; so are friendly
words like "PLEASE" and "NOW."  This way, PLEASE PUT A RED ROSE AND MY NOTE
ON THE SMALL TABLE NOW can be understood, while the game may be quite
confused by PLEASE YOUR MOTHER.


PREPOSITIONAL PHRASES

In some cases, the preposition need not be followed by an object (TURN THE
GAS STOVE ON is fine), but often the game will be puzzled unless you
provide one.  For example, UNLOCK THE PADLOCK WITH or PLACE THE BOOK BESIDE
just won't do.


COMMAND LINE OPTIONS

In order to accommodate as many hardware systems as possible, it is
possible to enter a "/B" option on the command line that invokes your
adventure game.  This causes the game to use the BIOS for all output,
rather than writing directly to the screen memory locations (which is
considerably faster and AGT's default mode of operation).  Some clones may
require this option.  Also, some multi-tasking environments (specifically,
DESQview) need this option to allow an AGT game to run in its own "window". 
If you find that an AGT game causes strange behavior on your screen, you

                                                                             31

should try this option.  For example, to play the game QUEST using this
option, you would start the game from the DOS prompt with "RUN QUEST /B".

There is one additional command line option available.  If you wish the
player's input to be in lower case, rather than AGT's default mode of upper
case, use the option "/L".  For example, to play CAVE with lower case
player input, start the game from the DOS prompt with "RUN CAVE /L".

                                                                             32

PART 2: HOW TO WRITE AN ADVENTURE GAME

                         
INTRODUCTION: WHY SHOULD I WRITE MY OWN ADVENTURE GAME?

Here are a few good reasons:

  - Imagine your office as an adventure game.  Imagine the wonderful
descriptions you could provide for your co-workers' offices, the analogies
you could make for the delivery people, and the thinly-veiled insults of
your boss you could include.  If such an adventure game scenario were
written in reasonable taste, it could serve as a well-deserved diversion on
a Friday afternoon.  Of course, if it's written in poor taste, and your
insults aren't veiled enough, it could be your last Friday.

  - Maybe you are trying to teach someone something.  Perhaps you want them
to learn about computers.  Maybe you want to guide them through many
screens of tutorials.  If you could write the text as an adventure game,
and make learning a game, the game players might learn faster and even have
fun doing it.  An excellent example of this is a series of spreadsheet
templates called Templates of Doom which has introduced Lotus 1-2-3 (in the
guise of an adventure game) to thousands of new spreadsheet users.  Another
excellent example is a game entitled Brainscape which teaches the anatomy
of the human brain by letting the player (who has been reduced to
microscopic size) explore the various "locations" of the brain in search of
human growth hormone and other "treasures" -- so the he can be restored to
normal size.

  - Or maybe you're well-equipped with a great imagination and you want to
develop a game that will rival the ones you've bought in stores or played
with friends.  Perhaps this is your chance to prove your fiction-writing
abilities.

  - Or last, but not least, because writing adventures is even more fun
than playing them.


HOW AN AGT ADVENTURE GAME WORKS


AN OVERVIEW

When a player begins to play an AGT game, the first thing the program does
is look on the disk for a title file (indicated by a .TTL file extension),
which should contain the name of the game, the author's name, and perhaps a
copyright statement.  Each line in the file is displayed centered on the
screen.

AGT also posts its copyright notice just below the game writer's title
information.  If, for some reason, there is no file with a .TTL extension,
the AGT copyright information is displayed by itself.  The title screen,
with the author's information and AGT's, stays on the screen while the

                                                                             33

program initializes all its data arrays and records and reads the various
compiled data file.

If the game's .DAT file contains some text preceded by the keywords INTRO
or INTRODUCTION and ended with the keyword END_INTRO, that text is
displayed at the beginning of the game.  It cannot be re-read during the
game.

In addition to the INTRO section of the .DAT file, there can also be an
instruction file with a .INS extension.  If such a file exists for the
adventure being played, before actual play begins AGT will ask the player
if he/she would like instructions.  If the answer if yes, this file will be
displayed.

Once all the data has been read and the player has had an opportunity to
read the game's instructions (if any), the program puts the player into
room 2 of the game (or another room if the author has specified an
alternative starting location).  There is no room 1; a location of 1
indicates the player's pockets.  AGT then prints the long text description
for room 2, (or the alternative starting location) and the player is asked
what to do.

Each time the player types in a command and <ENTER>, the program sends the
input line to the "parse" module.  The parser takes the input line, breaks
it into separate words, and tries to locate an addressee (if the command is
being directed to another character), a verb, a noun, a preposition, and
another noun as the object of the preposition.  It does this by eliminating
extra words like "THE" and "PLEASE"; and by checking and then eliminating
adjectives.  It returns up to five words: addressee, verb, noun,
preposition, and an object of the preposition.  (If any of these elements
is missing, the "empty string" ('') is returned in its place.)

If an invalid word is found by the parser, it informs the user, indicating
what part of speech AGT expected and which specific input command word it
didn't recognize.  Otherwise, the program then calls the execute module;
this section selects a procedure to call based on the verb (THROW, TAKE,
EAT, MOVE, etc.).  Depending on the procedure's own checking, the noun,
preposition and object might be rejected as invalid or, in some cases,
ignored partly or completely and an appropriate "error" message will be
given  For example, "EAT CASTLE" would typically cause the "error" message:
"It is impossible to eat the castle."

There are two ways a player can be moved to a new room.  One is by
specifically trying to do so.  Moving east is generally accomplished by
typing EAST or E or hitting the Right Arrow cursor key.  If the player
tries to move in a direction that is not allowed, AGT will inform him that
such a move is impossible.

The other way to move is by meeting a set of special requirements that the
game's author has defined as a "special."  The special might be defined, in
plain language, as "if the player is in the sauna, and he turns the faucet,
then move him to another room X."  That other room X might be anything.

                                                                             34

One possibility is that it may be a room with a similar or identical
description, but with a new exit or without an old one.  It might even be
the same room, but by executing the "special," the program displays several
lines of text.
      
In this case, the special text might be "You turn on the faucet, and
scalding hot water pours onto your feet.  You scream in agony and kick the
faucet, which is turned off."  If the author was cruel, the "special" here
might move the player to a new room called "hell" and be told "As you turn
the faucet, scalding hot water pours out onto your legs.  You scream in
agony, but the faucet won't shut off.  In minutes, you are scalded to
death.  You awaken in purgatory, where Satan tells you that your punishment
for killing the lizard [something the player did earlier to get here] will
be boiling in oil for eternity."  The new room description would describe a
vat of boiling oil, provide no exits, and include the keyword GAME_END to
end the game.

For relatively simple adventure games (i.e., Standard Level games),
"Specials" are the way you do almost anything unusual.  Of course, a
special can be used to move a player to a new room (i.e., TOUCH MIRROR
might cause the player to fall through the looking-glass and into a new
room).  But specials also allow a room to be "changed" in the player's view
-- this is accomplished by actually moving the player to a new, but similar
room.  If you want an airlock to close one door and open another, you use a
"special" which moves the player to a 'new' airlock with a different exit. 
If you want a player to 'teleport,' you use a special.  If you want to
player to be surprised by some action but not moved (i.e., PLAY STEREO
could lead to "Beethoven's Fifth plays loudly, awakening the neighbors. 
Someone pounds loudly on the ceiling"), use a special.  More examples of
"Specials" will be given later.


STANDARD LEVEL GAME FILES

Each Standard Level games can have up to three files: A title file (e.g.,
ALICE.TTL), an instruction file (e.g., ALICE.INS), and a data file
(ALICE.DAT).  Each of these file types will be explained in separate
sections to follow.


TITLE FILES

If there is a file with a .TTL extension, that file is displayed first
before the actual game play begins.  The contents of this file will be
displayed centered on a cleared screen.  For example, the title file for
the ALICE IN WONDERLAND game contained in the ALICE.TTL file is:

      The Adventures of Alice
      Who
      Went Through the Looking-Glass
      And
      Came Back

                                                                             35

      Though Not Much Changed
      Based on characters created by Lewis Carroll
      Game and Text Copyright 1986 D.A. Asherman
      
This would actually be centered on the screen as follows:

                             The Adventures of Alice
                                       Who
                         Went Through the Looking-Glass
                                       And
                                    Came Back
                             Though Not Much Changed
                  Based on characters created by Lewis Carroll
                   Game and Text Copyright 1986 D.A. Asherman
                                        

SETTING SCREEN COLORS

AGT sets the screen colors to be used during the adventure automatically. 
If the game is being played on a color monitor, the screen output is quite
colorful.  Specifically, the default screen colors will be:

      Normal text color is Cyan
      High lighted text color is Yellow
      Background color is Black
      Reverse text color is Red
      Reverse background color is Light Gray

These colors cause the normal screen output to be shown as "Cyan on Black",
while the player's input is shown as "Yellow on Black", and the status line
at the top of the screen is shown as "Red on Light Gray".

These default colors can be changed to specific different colors in the
first line of the .TTL file.  For example, if you wanted to change the
color combinations to normal output of "White on Blue", and player input of
"Yellow on Blue", and the status line of "Black on Cyan", then you are
specifying:

      Normal text color is White
      High lighted text color is Yellow
      Background color is Blue
      Reverse text color is Black
      Reverse background color is Cyan

This could be accomplished by putting the following line as the first line
of the .TTL file:

      COLORS WHITE YELLOW BLUE BLACK CYAN

                                                                             36

If you are playing the game on a monochrome monitor, most of the screen
output will be "White on Black", i.e., the normal monochrome output for
your monitor.  The only exceptions will be the player input which will be
shown high-lighted and the status line on the top of the screen which will
be shown in reverse, i.e., "Black on White".  On monochrome monitors, this
basic monochrome color combination will be used automatically regardless of
what may have been specified in the COLORS command in the first line of the
.TTL file.

It is also possible for the player to change the screen color combination
by giving input during the game.  For example, if the player inputs:

      COLORS YELLOW GREEN CYAN BLACK LIGHTGRAY

during the game, the screen will immediately change to "Yellow on Cyan",
with the player's input shown as "Green on Cyan", and the status line
displayed as "Black on Light Gray" -- if the game is being played on a
color monitor.  If the game is being played on a monochrome monitor, the
above player input would have no effect.  Other player color commands
allowed are:

      COLORS MONO

which changes the screen to a monochrome color combination - even on a
color monitor, and:

      COLORS DEFAULT

which will return the screen to AGT's default color combination --
depending upon the type of monitor the game is currently being played upon.


INSTRUCTIONS FILES

If there is a file with the correct filename and the suffix .INS, then AGT
will ask the player if he wished to read the instructions for the game.  If
the response is Y or YES, the filename.INS file will be displayed a screen
at a time with a pause between screens.  If the player responds with N or
NO, then the instructions will be skipped and the game will begin normally
in the starting room location.

If there is no .INS file, then the instruction prompt will not appear and
play will begin without any instructions.


THE WORK-HORSE .DAT FILE

Adventure games are really just a special kind of data base application. 
The game driver (for AGT, this is RUN.EXE) just accesses the adventure data
base to retrieve data based on the player's commands.  This is much like
how a "standard" data base application might display all employees in the
marketing department with salaries over a certain amount after getting a

                                                                             37

query from the data base user.  For Standard Level AGT games, the data base
is contained in the .DAT file.  This file is the real work-horse file for
AGT adventure games.  The most important data elements in an AGT game are
three large data arrays: the game's ROOMS, NOUNS, and CREATURES.  Each of
these data types will be explained in separate sections that follow.


ROOMS

The room specification in the .DAT data file is quite simple:

Required:

         |<-----significant----->|<------ignored------------------------>|
                                 |

          ROOM nnn                <-- nnn is a number from 2 to 199
          Room Name               <-- short room name (up to 30 characters),
                                      that will be shown on the status
                                      line (do not include comments!)
          {optional characteristics}
          END_ROOM

Optional characteristics:   <-- optional but at least one is
                                     strongly recommended

         |<---significant--->|<------ignored------------------------>|
                             |

          {direction} nnn     <-- nnn is a number from 2 to 199
                                  (default is 0)
                                  {any one of 12 directions can be
                                  specified, from the list:
                                     NORTH   NORTHEAST  UP
                                     SOUTH   SOUTHEAST  DOWN
                                     EAST    NORTHWEST  ENTER
                                     WEST    SOUTHWEST  EXIT}
          SPECIAL nnn         <-- optional, nnn is a room number.{If
                                  present, the current definition
                                  must include KEY nnn and there must
                                  be a SPECIAL nnn definition}
          KEY nnn             <-- nnn is a noun number (200-299)
                                  {activates special nnn}
          LIGHT nnn           <-- nnn is a noun number (200-299)
                                  OR the value 1 ("any light")
                                  {default is 0}
          POINTS nnn          <-- nnn is number of points player is
                                  awarded just for getting here.
                                  Default is 0.

                                                                             38

          LOCKED_DOOR         <-- default is FALSE.  If TRUE, AGT
                                  will act as if there is a locked
                                  door that cannot be opened in
                                  the room and give various
                                  appropriate messages if player
                                  tries to do something to the
                                  door.
          PLAYER_DEAD         <-- if this line is in the definition,
                                  the player dies as soon as he or she
                                  enters the room.
          GAME_END            <-- if this line is in the definition,
                                  the game ends as soon as the player
                                  enters the room (the room_descr
                                  is displayed, then the score).
                                 (Player loses game here.)
          GAME_WIN            <-- if this line is in the definition,
                                  the game ends as soon as the player
                                  enters the room (the room_descr
                                  is displayed, then the score).
                                  (Player wins game here.)
          ROOM_SYNONYMS       <-- default is NONE.  Room synonyms are
                                  indicated in the .DAT file as:
                                    ROOM_SYNONYMS MAGIC_WORD XYZZY SESAME
                                    ROOM_SYNONYMS CHANGE_LOCATION CLIMB
                                    ROOM_SYNONYMS PLAY SHOW DISPLAY FLASH
                                  These cause the first word (which must
                                  be a valid verb) to be substituted
                                  whenever the player enters one of the
                                  words following the first word in that
                                  room.  For example, if the player
                                  entered SHOW, DISPLAY, or FLASH (above),
                                  AGT would act as if the word PLAY (which
                                  is a "special") was entered and react
                                  accordingly.  There can only be one room
                                  synonym specification in each room.

It is recommended that at a minimum, one exit from each room be provided;
otherwise the player will be stuck in the room until he quits.  Of course,
that direction might be a special -- which will be explained in a later
section.

A room description should also be provided in .DAT file:

      ROOM_DESCR <nn>
      Some text, any number of lines, about the room.
      END_ROOM_DESCR

This room description will be what is printed whenever the player enters
the room or gives the command to LOOK.


                                                                             39

HELP MESSAGES

An optional HELP message may also be provided for each room:

      HELP <nn>
      Some text, any number of lines, gives a HELP message for this room.
      END_HELP_DESCR

If you don't enter a specific HELP message for a room, the default message
if the player asks for HELP is "Sorry, but you are on your own here."

Here is a more complete example of how a room might be specified in the
.DAT file:

      ROOM 32
      Top of Cliff
      NORTH 33
      SOUTH 34
      WEST 35
      END_ROOM

      ROOM_DESCR 32
      You are standing near the edge on the top of a tall cliff.  To the
      east is a sheer drop of several thousand feet.  To the north, west and
      south are paths that lead down the side of the mountain.
      END_ROOM_DESCR

      HELP 32
      Be careful, don't go too near the edge!
      END_HELP_DESCR


NOUNS

Nouns are necessarily more complex than rooms.  They are specified in the
following format, listed with the possible values (and defaults):

         |<-----significant----->|<------ignored------------------------>|
                                 |

          NOUN nnn                <-- nn is a number from 200 to 299
          Name                    <-- one-word name of the noun
          Adjective               <-- one-word adjective
          Short one-line description of the noun

          {other characteristics go here}-
          END_NOUN

      Other characteristics (optional):

          SIZE nn                 <-- nn is a number from 1 to 99+
                                        Default is 1.

                                                                             40

          WEIGHT nn               <-- nn is a number from 1 to 99+
                                      Default is 1.
          UNMOVABLE               <-- default is movable (carryable)           
          LOCATION nn             <-- nn is a "room" number (1-299, 1000)
                                      1 - if being carried
                                      2-199 - in room 2, etc.
                                      200-299 - inside another noun
                                      1000 - if being worn
          READABLE                <-- default is "not readable"
                                      {if READABLE then <TEXT nn>
                                       must also be defined}
          CLOSABLE                <-- default is "not closable"
          OPEN                    <-- default is "closed"
                                      {if open, then it can hold something}
                                      {if closed, it can not hold something}
          LOCKABLE                <-- default is not lockable
          LOCKED                  <-- default is unlocked
          KEY nn                  <-- default is 0
                                      {noun nn unlocks this noun
                                       if it's lockable}
          EDIBLE                  <-- default is inedible
          DRINKABLE               <-- default is undrinkable/solid
          POISONOUS               <-- default is nonpoisonous
                                      {predictable effect if poisonous
                                       edible/drinkable noun is eaten}
          ON                      <-- default is 'off'
          PUSHABLE                <-- default is not pushable
                                      {PUSH_DESCR nn recommended but
                                       not required if it is pushable}
          PULLABLE                <--  (ditto, PULL_DESCR nn)
          PLAYABLE                <--  (ditto, PLAY_DESCR nn)
          TURNABLE                <--  (ditto, TURN_DESCR nn)
          IS_LIGHT                <-- default is NOT is_light
                                          (IS_LIGHT -> illuminates any room
                                          defined as LIGHT 1 or LIGHT nnn
                                          where nnn is the noun number)
          POINTS                  <-- default is 0 (points awarded to player
                                         if object is being carried,
                                         present or in the "treasure" room  
                                         at game_end)
          GAME_WIN                <-- default is FALSE.  Player wins game
                                          if TRUE when he get this noun.
          CAN_SHOOT               <-- default is can't shoot (can the
                                          weapon be used to shoot a
                                          creature? if not, it must be
                                          thrown)
          NUM_SHOTS               <-- default is 0 (how many bullets/
                                          charges are there initially?
                                          decremented each time the noun is
                                          fired.)
          WEARABLE                <-- default is not wearable

                                                                             41

          POSITION                <-- default in NONE.  If the game designer
                                          wishes to have a noun's original
                                          position as "(behind the tree)"
                                          he would have:
                                          POSITION behind the tree
                                          in the .DAT file.  The verbs
                                          PUT/PLACE and GET/TAKE change the
                                          noun's position.
          SINGULAR                <-- default is SINGULAR.  The only
                                          alternative is PLURAL.  AGT
                                          verbs/pronouns will be singular
                                          or plural depending upon this
                                          value.
          NOUN_SYNONYMS           <-- default is NONE.  If the .DAT file had
                                          NOUN_SYNONYMS GOLD COIN COINS
                                          then all of these words would be
                                          accepted as valid synonyms for
                                          this noun.  Of course, the
                                          "official" NAME will also work.

Note: To 'spice up' the game, you might want to put things inside other
things initially, so the player has to open everything to be sure s/he
doesn't miss anything important.  Be logical, though: a refrigerator seems
likely to be open-able, but a crabapple probably ought to be 'closed' and
'unclosable' and thus unable to contain something else.

Similar to the complete room descriptions, there is a way to specify a
lengthy description of a noun by using a NOUN_DESCR in the .DAT file.  When
the player gives the command to EXAMINE the noun, this description will be
displayed on the screen.


TEXT

If a noun is readable, the description that is printed whenever the player
gives the command to READ it is contained in a TEXT description in the .DAT
file.  Thus, the following would be a valid set of definitions:

      NOUN 232
      Book
      Red
      There is a small red book here.
      WEIGHT 1
      SIZE 3
      LOCATION 32
      READABLE
      NOUN_SYNONYMS Cover Title
      END_NOUN

                                                                             42

      NOUN_DESCR 232
      The red book is quite thin, and has a hard cover.  There is writing on
      the book's cover.
      END_NOUN_DESCR

      TEXT 232
      The title of the book is "The Wisdom of Ronald Reagan."  The pages are
      all blank.
      END_TEXT


MULTIPLE NOUNS WITH THE SAME NAME

AGT allows multiple nouns with the same name.  The parser examines the
current room and player environment and assumes that if only one noun with
a particular name is in the room then that must be the noun that the player
meant as the NOUN or OBJECT of his command.  If there is more than one noun
with the same name in the room, the parser gives an "error" message and
asks the player to be more specific about which NOUN (or OBJECT) he means. 
For example, if there are three kinds of trees in the "room" and the player
had entered the command to EXAMINE TREES, the parser would ask for the
clarification: "Which 'TREES', the OLIVE TREES or the OAK TREES or the PINE
TREES?" The player could then enter any response with one of the proper
adjectives to specify which trees were meant, i.e., any of these responses
would tell the parser that the OAK trees were correct:

      THE OAK TREES
      EXAMINE THE OAKS
      OAK
      THE OAKS, YOU OAF!!

If the player still doesn't enter a response with one of the proper
adjectives, a message is given that asks the player to re-enter his command
using the NOUN's adjective to clarify which NOUN is meant.  This means that
if there are two or more nouns with the same name, their adjectives must be
unique, i.e., you can have a RED BOWL and a GREEN BOWL, but the game should
not contain two RED BOWLs (at least it should not have two of them if they
can be together in the same room.)


PUSH, PULL, TURN, AND PLAY DESCRIPTIONS

Similar to TEXT descriptions if a noun is readable, you may also give
unique descriptions if a noun is described as being pushable, playable,
turnable, or pullable and the player takes one of those actions with the
noun.  These descriptions are included in the .DAT file as a PUSH_DESCR,
PULL_DESCR, TURN_DESCR and PLAY_DESCR.  They will be displayed only if the
player takes the specified action AND that action does not activate a
SPECIAL for the current room.  If there is no description provided, a
standard ("nothing happens" or something equally appropriate) message is
provided.

                                                                             43

For example, if you want to generate messages whenever the player gives the
commands to PLAY RADIO or to TURN ON RADIO or TURN DIAL, you could set up
the following in the .DAT file:

      NOUN 218
      Radio
      Portable
      There is a large "ghetto blaster" portable radio here.
      MOVABLE
      WEIGHT 10
      SIZE 10
      NOUN_SYNONYMS GHETTO BLASTER DIAL DIALS KNOB KNOBS
      PLAYABLE
      TURNABLE
      END_NOUN

      NOUN_DESCR 218
      The radio is barely portable.  It weighs about 47 pounds and must be
      carried with both hands.  It has many dials and knobs.
      END_NOUN_DESCR

      PLAY_DESCR 218
      As you turn on the radio, you hear a song by "Duran Duran."  After a
      few moments, you become bored with the music and you turn the radio
      off.
      END_PLAY_DESCR

      TURN_DESCR 218
      As you turn the dial on the radio, you hear the Beatles singing
      "Yesterday".  This sounds like a good station and you stop turning the
      dial.  The music sounds nice and you sing along softly.
      END_TURN_DESCR


EATING, DRINKING, AND DYING

Any object defined as EDIBLE can be eaten.  Any object defined as DRINKABLE
can be drunk.  And any object defined as POISONOUS will kill the player if
s/he eats or drinks it.  POISONOUS has no effect if the noun is neither
edible nor drinkable.  In most situations, it is considered poor sport to
make completely non-threatening and logically edible things poisonous; it
is likewise questionable to make packages of rat poison edible but
non-poisonous.

When a noun is eaten or drunk it normally disappears (into the player's
stomach -- naturally).  The only exception to this is when the noun is
unmovable.  This makes it possible for the player to drink from a lake
without having all the water (or the lake itself) disappear.


                                                                             44

WEIGHT AND SIZE

Those values are there for a reason.  No player can lift an object heavier
than 100, even if it's defined as MOVABLE.  Likewise, objects whose size is
more than 100 are too awkward to be carried.  The total weight the player
can carry is 100, so the player cannot carry two 60-weight objects at once. 
Total size limit is also 100.  It is considered poor sport to assign large
weight values to feathers and low values to large slabs of steel, but cruel
game writers are able to do so.  Likewise, a game will be less baffling if
small objects (pens, tin cans) have small size values and large ones
(desks, cars) are larger.

IMPORTANT NOTE: Size is also very important when dealing with "containers". 
A container will only be able to contain things whose total size is less
than the size of the container.  For example, if you have a knapsack whose
size is 10, it will be able to hold a flashlight of size 2, a sandwich of
size 1, and long rope of size 6.  If the player tries to put something else
(e.g., a compass of size 3) into the knapsack, he/she will get a message
that "The compass will not fit into the knapsack".


LIGHT AND DARKNESS
      
If a room has a LIGHT value other than 0 (the default), the room will
appear pitch black if the player wanders in empty-handed.  There are two
"types" of lights and two types of darkness.  A noun may be defined as
being a light by specifying the word IS_LIGHT in its definition; in this
case, it will light any dark room defined as LIGHT 1.  The light value of 1
in a room definition means that any light will make the room visible.  Of
course, these "general-purpose" lights must be turned on to light the room,
and thus all LIGHTs can be TURNed ON and OFF (or LIGHTed and EXTINGUISHed).

If the LIGHT value is other than 1 (i.e., LIGHT 218), only the noun with
the matching number will make the room's contents visible.  This is useful
if the darkness comes from something other than an absence of light: for
example, a fan might be the only object that makes a smokey room clear
enough to see in.  A special-purpose light need not be defined as a light
(i.e., it doesn't have to be defined IS_LIGHT), nor does it have to be on,
to work as a light in a room with that noun as a LIGHT.  A noun can
function as a special-purpose light for more than one room, but each room
can only be lit by one special-purpose light.  (A room with a LIGHT value
of 1 will be lit by ANY noun defined as IS_LIGHT.)


CREATURES

Any living thing is identified as a 'creature', and can be either
'friendly' or 'hostile'.  Friendly creatures are quite passive; hostile
creatures are not quite as friendly.  It is recommended that provisions be
made for a weapon to kill any hostile creatures.  For fairness, that weapon
should be accessible by the player before s/he meets the hostile creature.

                                                                             45

Players should be discouraged from wild and unwarranted killing: i.e., they
ought not kill friendly creatures.  If no weapon will kill the creature
(i.e.,  if you leave or specify WEAPON as the default value 0), the player
cannot kill it.  For friendly creatures, you should not lead the player on
by making the weapon something unexpected: if the player kindly offers a
jelly bean to the friendly creature, it ought not be fatal.  Only one
weapon can kill any given creature, but the same weapon might be used to
kill many creatures.

The format in the .DAT file for Creatures, like rooms, are relatively
simple:

         |<-----significant----->|<------ignored------------------------>|
                                 |
Required:

          CREATURE nnn            <-- nnn is a number from 300 to 399
          Name                    <-- one word name
          Adjective               <-- one word adjective
          Short one-line description of creature.
          {optional characteristics}
          END_CREATURE

Optional:

          LOCATION nn             <-- nn is a room number from 1 to 199.
                                      {default is 0}
          WEAPON nn               <-- nn is a noun number from 200 to 299
                                      {default is 0}
                                      {noun nnn kills this creature}
          HOSTILE                 <-- default is friendly
          THRESHOLD n             <-- {n is number of times a hostile        
                                     creature can be unsuccessfully         
                                     attacked before it
                                      kills the player - default 3}
          TIME_THRESH n           <-- {n is number of turns player can be
                                      in the same room with the creature
                                      before it kills the player - default
                                      value is infinite, or disabled}
          POINTS nn               <-- nn is the number of points player
                                      gets for having this creature in the
                                      current room, i.e., for "capturing"
                                      or "rescuing" the creature.
                                      {default is 0}
          GROUPMEMBER             <-- default is NOT a GroupMember.  If a
                                      creature is specified as a GROUPMEMBER
                                      then it will automatically follow the
                                      player from location to location once
                                      they meet.

                                                                             46

          GENDER                  <-- default is THING.  GENDER may also be
                                      specified as MAN or WOMAN.  GENDER
                                      causes pronouns and verbs to be used
                                      that are appropriate to the specific
                                      creature.  THINGs are ferocious and
                                      referred to as "IT".  MANs are less
                                      ferocious and are referred to as
                                      "HE" and "HIM".  WOMANs are "SHE"
                                      and "HER".
          CREATURE_SYNONYMS       <-- default is NONE.  If the .DAT file had
                                      CREATURE_SYNONYMS BOB BILLY then all
                                      of these names would be accepted as
                                      valid synonyms for the creature.
                                      Of course, the "official" NAME will
                                      also work.

NOTE: A player cannot exit a room containing a hostile creature.  When
killed, creatures are relocated to LOCATION 0.  Friendly/non-hostile
creatures have no effect on the (Standard Level) game's outcome -- they
just add a little "spice" to the game.

For example, to define a female Froobious Bandersnatch in room 9, which can
be killed with noun 205, we could use the following specifications in the
.DAT file:

      CREATURE 301
      Bandersnatch
      Froobious
      There is a mommy froobious bandersnatch, looking for her cubs.
      LOCATION 9
      WEAPON 205
      THRESHOLD 2
      TIME_THRESH 5
      WOMAN
      HOSTILE
      CREATURE_SYNONYMS BEAST
      END_CREATURE

The thresholds specify that you can try to attack the bandersnatch twice
(unsuccessfully) or be in the room with the bandersnatch for 5 turns,
before the beast kills you.  The player will not be able to leave the room
if the Bandersnatch is present, because she is hostile, until the creature
has been killed (with weapon 205).  To use the weapon to kill the creature,
the player would FIRE THE GUN AT THE BANDERSNATCH or SHOOT THE BEAST WITH
THE GUN, if the weapon is a gun, or THROW the weapon AT the creature or
KILL the creature WITH the weapon, if the weapon is not a gun.

The complete EXAMINE description might be contained in the .DAT file as:

                                                                             47

      CREATURE_DESCR 301
      The bandersnatch is snorting and drooling.  It is a large female and
      she appears to have misplaced her cubs, which makes her very un-
      pleasant and very dangerous.  She seems to harbor few honorable
      intentions towards you.
      END_CREATURE_DESCR


GROUPS OF CREATURES

Creatures can be designated as a member of the "Group" by using the
GROUPMEMBER specification.  All group members in the current location will
automatically move with the player when he/she moves to another location. 
However, their group status will not effect other aspects of their behavior
during the game, i.e., they can still be talked to or killed as
individuals.  Probably the best known example of an adventure creature
following the player once they meet is the Robot Floyd who is the player's
constant companion in the Infocom adventure games Planetfall and its sequel
Stationfall.  The group can have several members, so this feature could be
used to beam down a "landing party" consisting of the player, Spock, Sulu,
McCoy and Scotty and have them explore the planet as a group in a Star Trek
adventure.

Section 4. of this manual introduces a variety of meta-commands that enable
the game designer to test the status of the group and to manipulate the
group in many ways, i.e., add or subtract members, disband the group, send
the group off to another location, etc.


SPECIALS

To 'activate' the special, the player must 'do something' to the noun
specified as the room's KEY.  This can include turning it, pushing it,
pulling it, or playing it (depending on what can be done to the noun as
defined).  If the proper action is taken on the noun while in the room, the
player will be relocated to the room specified in the SPECIAL line and the
SPECIAL nn text will be displayed.  (If the Special points to the current
room, the only effect apparent to the reader will be the display of the
SPECIAL text.)

For example, to enter the house (by going to the entry hall -- ROOM 14) by
pushing the door bell on the porch (ROOM 13) could be done with the
following special:

      ROOM 13
      Front Porch
        .
        .
        .
      SPECIAL 14 (* Entry Hall *)
      KEY 222 (* Door Bell *)
      END_ROOM

                                                                             48

      ROOM_DESCR 13
      You are standing on the front porch of a large mansion.  The doors are
      about 10 feet high.
      END_ROOM_DESCR

      NOUN 222
      Bell
      Door
      Beside the door in a door bell.
        .
        .
      PUSHABLE
      UNMOVABLE
      LOCATION 13 (* Front Porch *)
      NOUN_SYNONYMS doorbell
      END_NOUN

      SPECIAL 14
      You boldly push the door bell.  Deep inside the house, you hear some
      chimes that sound vaguely like Big Ben.  After a few minutes, the door
      is opened by a butler dressed in a black morning coat.  He says "Good
      morning, Sir.  I will tell the Master that you have arrived."  With
      that, he disappears down the hall.  You are left alone in the entry
      hall of the house.
      END_SPECIAL

      ROOM 14
      Entry Hall
      NORTH 15
        .
        .
      END_ROOM

      ROOM_DESCR 14
      The entry hall is long and narrow.  You can see open doors at the end
      of the hall to the north.  The front doors are behind you to the
      south.
      END_ROOM_DESCR


"SPECIAL" SPECIALS

AGT has two "special" specials: the verbs MAGIC_WORD and CHANGE_LOCATION. 
These words are used in conjunction with a room synonym declaration to
create a "special" for any words the game designer may wish to use (i.e.,
you are not restricted to PULL, PUSH, TURN and PLAY).  For example, the
designer may specify that XYZZY and MAGIC_WORD are synonyms in a particular
room -- so that if the player gives the command XYZZY in that room, it
causes a "special" for that room which might send the player to another
room with an appropriate "special" messages being written.  CHANGE_LOCATION
works the same way except it requires a specific NOUN that is the "key" to
the "special" to be present in the room.  For example, the game designer

                                                                             49

might make SHOW a synonym for CHANGE_LOCATION in particular room and make
the noun PASS the "key" to the "special" in that room, then whenever the
player gives the command SHOW THE PASS TO THE GUARD (in the particular
room), the "special" would be executed and a message like "The guard
examines your security pass and finds it in order.  He opens the steel door
and allows you to enter the vault, where you find...."

NOTE: In AGT, each room may have only one special.  So, you will not be
able to have a MAGIC_WORD and another special in the same room. (You could,
however, achieve similar results using meta-commands.)

For example, in order to be able to define a special for CLIMB TREE or
SCALE TREE to cause the player to go from room 10 to room 15 with a special
message, the game designer could use the following specifications in his
data file:

      ROOM 10
      Dark Forest
        .
        .
      SPECIAL 15 (* Top of Tree *)
      KEY 221 (* Oak Tree *)
      ROOM_SYNONYMS CHANGE_LOCATION CLIMB SCALE
      END_ROOM

      NOUN 221
      tree
      oak
      There is a large oak tree at the edge of the clearing.
        .
        .
      UNMOVABLE
      LOCATION 10 (* in Dark Forest *)
      END_NOUN

      SPECIAL 15
      You manage to climb up to the top of the oak tree.
      END_SPECIAL

      ROOM 15
      Top of Oak Tree
         .
         .
      DOWN 10 (* going DOWN puts you back in the dark forest *)
      END_ROOM

MAGIC_WORD works the same way except, the KEY for the room must be zero. 
For example, if you wish to allow the player to go from room 23 to room 44
when he gives the commands SESAME, SHAZAM or ABRACADABRA you would do it as
follows:

                                                                             50

      ROOM 23
      Emperor's Tomb
        .
        .
      SPECIAL 44
      KEY 0
      ROOM_SYNONYMS MAGIC_WORD SESAME SHAZAM ABRACADABRA
      END_ROOM

      SPECIAL 44
      By saying the magic word $VERB$, you are suddenly transported to the
      outside of the Emperor's Tomb.  You are very lucky to have escaped,
      because the air in the tomb was almost gone.
      END_SPECIAL

      ROOM 44
      Outside Tomb Entrance
        .
        .
      END_ROOM

In this example, the SPECIAL message uses a very convenient and helpful
feature of AGT, namely $VERB$.  This causes the original verb to be
repeated back in the message, i.e., if the command was SHAZAM, then the
special message would be "By saying the magic word SHAZAM, you are suddenly
transported..."  Similarly, in AGT, the game designer may also have the
NOUN, the noun's ADJECTIVE, the PREPOSITION and the OBJECT of the commands
repeated back in messages by specifying $NOUN$, $ADJECTIVE$, $PREPOSITION$
and $OBJECT$ within the message text.  If a command is being addressed to a
character in the adventure, e.g., SCOTTY, BEAM ME UP, the character's name
may also be echoed back in a message by using $NAME$.

IMPORTANT NOTE:  The $-words are case-sensitive.  For example, if you use
$NAME$, you will get the name echoed back to the player in the game in all
caps.  If you use $Name$, you will get the first letter of the name
capitalized and the remainder in lower case.  If you use $name$, you will
get the name displayed in all lower case letters.  These same case rules
also apply to the other $-words, i.e., $Verb$ will cause the verb to be
repeated back with its first letter capitalized and the other letters lower
case.


CREATING A TYPICAL ROOM

Let's suppose that your game contains a bedroom, connected to a closet, a
bathroom, and a hallway.  In the bedroom are a lamp, a bed, a dresser, a
mirror, and a werewolf.

First, you want to define the room itself:

                                                                             51

      ROOM 34
      Master Bedroom
      WEST 33                 (33 is the hallway)
      EAST 35                 (35 is the bathroom)
      NORTHEAST 36            (36 is the closet)
      END_ROOM

A description of the room is appropriate here:

      ROOM_DESCR 34
      This is the master bedroom, where Mommy and Daddy usually sleep. 
      Plainly visible in the room are a bed, a dresser, a lamp, and a large
      wall mirror.  The room smells horrible, as if a large, unclean animal
      had been here recently.
      END_ROOM_DESCR

Note that this description mentions the nouns that are initially in the
room.  This is OK, since all of the nouns are UNMOVABLE, but if they could
be taken by the player, they should not be described in the room
description since they may not be there if the player should return.

That werewolf is begging to be described, too:

      CREATURE 315
      Werewolf
      Black
      There is a menacing black werewolf here.
      LOCATION 34
      WEAPON 217                      <-- Noun 217 will kill it
      HOSTILE                         <-- ever met a friendly werewolf?
      END_CREATURE

      CREATURE_DESCR 315
      The werewolf is about the size of a small horse.  Its matted fur
      stinks, and a sickening smell emerges from its open mouth, through
      which you can see sharp, large teeth.
      END_CREATURE_DESCR

A HELP message might be given as follows:

      HELP 34
      The werewolf looks dangerous.  Perhaps, you should get out of here as
      fast as you can.
      END_HELP

Finally, each noun within the room ought to be defined and described:

                                                                             52

      NOUN 220
      Bed
      Large
      There is a large (king-size) bed here.
      LOCATION 34
      UNMOVABLE
      END_NOUN

      NOUN_DESCR 220
      The bed is quite ordinary.
      END_NOUN_DESCR

      NOUN 221
      Dresser
      Wooden
      There is a large wooden dresser here.
      LOCATION 34
      CLOSABLE
      CLOSED
      UNMOVABLE
      END_NOUN

      NOUN_DESCR 221
      The wooden dresser looks pretty much like most wooden dressers.
      END_NOUN_DESCR

      NOUN 222
      Lamp
      Small
      There is a lamp on the dresser.
      LOCATION 34
      UNMOVABLE
      END_NOUN

      NOUN_DESCR 222
      The small table lamp is pink and has a green shade.
      END_NOUN_DESCR

      NOUN 223
      Mirror
      Strange
      There is a wall-size mirror here.
      LOCATION 34
      UNMOVABLE
      END_NOUN

      NOUN_DESCR 223
      As you gaze into the mirror, you sense something unusual about it.  It
      seems to shimmer, and your reflection seems somehow unreal, as if the
      mirror weren't really there at all.
      END_NOUN_DESCR

                                                                             53

Hmm.  That mirror seems rather interesting.  Maybe you could make a
"special" out of it.  For example: when the player touches it, s/he is sent
to room 50, the mystic cavern of the Wizardess.  To do so, you need to add
a "special" to room 34 and specify the mirror as its key, and you need to
make the mirror touchable.  (Note: "touch" and "push" are synonyms -- but,
you should use the word "push," not the word "touch," in your definitions.)

      ROOM 34
      Master Bedroom
      WEST 33                 (33 is the hallway)
      EAST 35                 (35 is the bathroom)
      NORTHEAST 36            (36 is the closet)
      SPECIAL 50              <-- Special goes to room 50 (cavern)
      KEY 223                 <-- Special activated by touching mirror
      END_ROOM

      NOUN 223
      Mirror
      Strange
      There is a wall-size mirror here.
      LOCATION 34
      UNMOVABLE
      PUSHABLE                <-- Here's how we'll activate the special
      END_NOUN

The player will see room 50's description when s/he gets there, but the
SPECIAL text for room 50 will be displayed first:

      SPECIAL 50
      You reach out to touch the mirror, and are shocked to find that your
      fingers vanish through the surface.  Before you can react, you feel
      yourself drawn forward through the mirror, and into a black nothing-
      ness.  You look back to try to see the mirror, but everything is
      black.

      You are falling, but not very quickly -- it's almost as if you are
      floating.  As you fall, your eyes begin to adjust to the darkness. 
      Then, suddenly, you land on a soft cushion of some sort.  As you rest
      on the cushion, your eyes adjust to the very dim light of this new
      room.
      END_SPECIAL

(Note that usually, you'd want to have a PUSH_DESCR  prepared for when the
player touches a noun when it doesn't activate a special, but the mirror
can't be moved so it will always activate a special when Touched.)


"INVISIBLE" NOUNS

Occasionally, you will want to have a noun that does not have a separate
description line when you see the room's description, i.e., you want to
have an "invisible" noun.  The most common instance of these is an

                                                                             54

UNMOVABLE noun whose description is incorporated in the room description.
This is accomplished by having the first word in the "one-line" description
of the noun be the word "INVISIBLE."  For example, below is an invisible
bunch of toys which can be EXAMINEd and PLAYed with, but its basic
description is contained within the room's description.

      ROOM 4
      Santa's Workshop
      EAST 2 (* Bunkhouse *)
      WEST 8 (* Garage *)
      SOUTH 5 (* Gift Wrapping Room *)
      NORTH 9 (* Outside Workshop *)
      END_ROOM

      ROOM_DESCR 4
      This is Santa's Workshop.  Not many people have laid their eyes on
      this room.  All around you is a clutter of toys, in various stages of
      development and tools of all descriptions.  To the north there is a
      door.  Doors also lie to the south, east and west.  Work benches line
      all four walls.  Above each bench is a peg board full of hooks.  Tools
      hang from the hooks.  The tops of the benches are covered with an
      array of items, from scraps of building materials, the odd nail and
      screw, paint brushes, cans of paint some open and some closed to
      blueprints and plans of toys.  The floor is cluttered with toys. 
      These toys represent just about every stage of development possible. 
      In fact the clutter on the floor is so bad, that you have to kick a
      path in order to move about the room.
      END_ROOM_DESCR

      NOUN 218
      toys
      many
      INVISIBLE  --  description in room description
      UNMOVABLE
      LOCATION 4 (* Santa's Workshop *)
      PLAYABLE
      PLURAL
      NOUN_SYNONYMS toy sleds toboggans skates skis dolls trains car cars
      END_NOUN

      NOUN_DESCR 218
      This is what Santa's part of Christmas is all about...TOYS!  There are
      so many, that it's hard to begin to describe what you see.  The first
      thing you notice is that there seems be a lot more than when you were
      around.  The world's population must have doubled in the few short
      years of your retirement.  The sleds and toboggans have the 'New and
      Improved' look.  There's not much change in the design and style of
      the skates and skis, just better materials to work with.  Now the
      dolls are a different story. You see your standard 'cry-and-wet' doll,
      rag dolls, the so-called fashion doll and the new 'vegetable-patch'
      doll. The biggest change in the dolls is the talking dolls.  Computer
      chips are a miracle-come-true.  These dolls have real voices...nothing

                                                                             55

      tinny about the quality of the sound.  From the number of them here,
      you would guess that at least 4 out of 5 good girls are going to find
      one of these little gems under their Christmas Tree tomorrow morning. 
      Over in the corner you spy the electric trains.  Santa and his 'toy
      architects' have left this design alone.  They look the same and
      operate the same.  The next thing you ogle over are the racing cars
      sets.  The cars are sleek and fast!  Not to mention the slick surface
      of the track.  Too bad you have a mission.  You'd love to sit and
      pretend you're A. J. Foyt.  The little ones will be pleased that
      Santa's elves have made up the latest stuffed toys.  Alf seems to be
      the most popular.  You really don't have much time to look at all the
      toys.  You have a mission, remember?  One last quick scan of the room,
      just to make sure that the usually rocking horses and bicycles are
      present and accounted for.
      END_NOUN_DESCR

      PLAY_DESCR 218
      Sorry, but you don't have time to play with the toys.  You have to
      help Santa make Christmas a success this year.
      END_PLAY_DESCR

Notice, that the toy noun must be UNMOVABLE for this scenario to work the
way it should.


SCORING

The player's progress in the game is reported in two ways: the number of
rooms visited, and the number of points currently held.  The player
receives the defined number of points for visiting each room (default point
value is 0), and for possessing (i.e., carrying, wearing or in the current
room or in the treasure room) each noun (or creature with points) when
scoring is done.  The point defaults for both nouns and creatures are zero. 
Players get no points for having eaten something, since objects which are
eaten or drunk are removed from the game.

For best results, it is best to assign a point value to each room which the
player arrives at after solving some puzzle.  It's also wise to award a few
points for out-of-the-way rooms.  Objects should only have point values if
they can reasonably be expected to be carried at the end of game -- if an
object is too heavy to be lifted or moved, it's not logical to assign it a
point value.


OTHER DATA ITEMS IN THE .DAT FILE


INTRODUCTION or INTRO TEXT

In the .DAT file, you can include some introductory remarks by using the
header INTRO or INTRODUCTION and ending these remarks with END_INTRO. 
These kinds of remarks are particularly useful for telling the player what

                                                                             56

has happened prior to his arrival in the game's starting room.  As an
example, see the game "played" in the manual's PREFACE.  All of the text
prior to the part that begins with "You are in a deep pit" was contained in
the INTRODUCTION text section of this game's .DAT file.  The introductory
text is displayed during the game's initialization and cannot be re-read
later.  It also cannot be skipped over.


STARTING ROOM

An AGT adventure normally starts in room number 2.  This location can be
over-ridden by specifying an alternative location in the .DAT file.  For
example, if the .DAT file had:

      STARTING_ROOM 23

then the game would start in room 23.


RESURRECTION_ROOM

You can now specify a room to have the player resurrected in.  The starting
room is the default resurrection location, but you now specify an
alternative room.  For example, by putting the following line in your .DAT
file, you can cause the player to be resurrected in room number 12:

      RESURRECTION_ROOM 12


MAX_LIVES

You can also specify the number of times the player can be resurrected in
the game.  For example, by putting the following in the .DAT file, you
would set the number of player lives to 5:

      MAX_LIVES 5

The default is 3 lives.  If you set MAX_LIVES to zero, the player will
never be resurrected.


TREASURE ROOM

Normally, the player only gets points for visiting rooms and for possessing
treasures (i.e., nouns or creatures with value).  However, many classic
adventure games use a convention that required the player to bring his
various treasures to a "Treasure Room".  Probably, the best example of this
is the Well House in the original "Colossal Cave" adventure.  AGT adds this
feature by allowing the game designer to specify a treasure room in the
.DAT file as:

      TREASURE_ROOM 41 (or wherever)

                                                                             57

Normally, there is no treasure room.  This option is only activated if a
statement like the above appears in the .DAT file.


VERB SYNONYMS

To specify verb synonyms, simply create a AGT definition starting with VERB
(alone on a line) and ending with END_VERB (alone on a line).  For example:

      VERB
      KILL STAB CHOP
      ATTACK STRANGLE CHOKE THROTTLE
      UP CLIMB ASCEND
      END_VERB

In the above example, if the player types STAB THE DWARF WITH THE KNIFE,
AGT will translate the sentence to KILL THE DWARF WITH THE KNIFE and
attempt to do so.  Synonyms do not replace the original verb, e.g., the
verb KILL would also work.  Likewise, if the player types CLIMB the game
will execute the sentence as if the player had typed UP -- which means that
CLIMB DOWN would be translated to UP DOWN which would, of course, confuse
the game somewhat and generate an error message which might, in turn,
confuse the player.

Because the verb synonyms are not actually user-defined verbs, you should
think carefully about the possible uses of words you add, to make sure the
player won't be confused by the meaning of a word.

WARNING: It is NOT possible to define a synonym for a synonym.  For
example, the following entry would generate an error message:

      VERB
      ATTACK CHOKE
      CHOKE STRANGLE    <-- "Verb not recognized - Line ignored"
      END_VERB

Verb synonyms defined as those above are "global" in that they apply in
each room of the game.  On the other hand, room synonyms apply only in the
particular room for which they are defined.  Room synonyms take precedence
over global synonyms.  For example, you could define CHOKE to be a synonym
for ATTACK globally (as above), then define CHOKE to be a synonym for PULL
in a particular room.  If you were in that room, CHOKE would be treated
like the verb PULL; outside of that room CHOKE would be treated as if you
had input the verb ATTACK.


PLAYER_DEAD

A ROOM can contain a PLAYER_DEAD specification that will cause the player
to die when he or she first enters the room (and after the description is
displayed on the screen).  An example of how this feature might be used is
as follows:

                                                                             58

      ROOM 35
      You have drowned!
      PLAYER_DEAD
      END_ROOM

      ROOM_DESCR 35
      Now you've done it!  You've slid off the floe into the frigid water. 
      Your life passes before your eyes.  They say drowning is not such a
      bad way to go, but whoever said that must have drowned in warm water. 
      Your frozen little body bobs to the surface for a second then flips
      upside down and you sink to the bottom of the ocean.  You're dead!
      END_ROOM_DESCR


GAME_WIN
      
Acquiring all the points defined in the game doesn't let the player "win,"
and winning isn't even related to points.  If you define a room as
GAME_WIN, then the player wins the game upon entering the room, and the
game ends and the final score is displayed.  It is usually desirable to
make that room very difficult to enter and not let the player get there
unless he or she has done everything else there is to do.
      
The room description is displayed, so you should put your congratulatory
description there.  For example:

      ROOM 21
      End of the Rainbow
      GAME_WIN
      POINTS 50
      END_ROOM

      ROOM_DESCR 21
      At long last, you have reached the end of the rainbow.  The pot of
      gold lies at your feet.  You have won the game!!
      END_ROOM_DESCR

Note that is also possible to win the game when a specific Noun is
acquired.  This is done be putting a GAME_WIN in the Noun's specification.


GAME_END

If you desire to have the game end, without having the player win, you can
use a GAME_END in the room definition.  When this is done, the game will
end when the player enters the room and the final score is displayed.  The
room description is also displayed, so you should put any final comments to
the player in the room description.  For example:

                                                                             59

      ROOM 26
      End of the trail
      GAME_END
      END_ROOM

      ROOM_DESCR 26
      You have reached the end of the trail.  There is no turning back.
      Sorry, but your adventure is OVER!
      END_ROOM_DESCR


PAGE PAUSES

Normally, the game pauses after every 22 lines of text (so that the player
can read it), and the player then hits <CR> to read more.  As you play-test
your game, you might try to adjust your paragraph or line spacing so that
the page breaks don't come at awkward spots and confuse the player.  This
is probably most important in the title screen and the INSTRUCTION and
INTRO texts; it is less controllable in the individual room descriptions.


ORDER OF DEFINITIONS
      
AGT doesn't require that the definitions be in any specific order within
the data files.  Definitions can be freely mixed throughout your data
files.  You'll probably want to group items together that logically belong
together. That's how the sample games were written.  The order of
definitions in the file has no effect on game performance, as long as each
definition is properly structured.


HOW TO INCLUDE COMMENTS IN YOUR AGT DATA FILES

Within your data file, you'll probably want to include comments which won't
be processed by the game itself, so you'll be able to understand why you
did certain things.

In general, AGT treats anything it doesn't understand as a comment.  Thus,
if you have a paragraph of text in between definitions, AGT will usually
ignore it.

BEWARE: If one of the lines in the paragraph begins with a keyword like
"noun" or "text," AGT will probably decide that it's the beginning of a
definition and get confused.

To avoid this, you can use a nonsense word to start each line of a comment:
words like "REM" (for remark) are useful since they also clearly state what
the line is.

AGT ignores most punctuation completely, so using "comment" indicators like
"(*" and "*)" or { and } at the beginning of a line won't help.  However,
using these kinds of comment indicators will make your game files easier to

                                                                             60

read.  AGT usually only sees alphabetic characters ('a'..'z' and 'A'..'Z')
or the digits ('0'..'9').

You can put comments on lines which contain a keyword or a keyword and a
number; don't include comments on lines which contain a full-line
description.

Example of properly-commented definitions:
      
      ROOM 34
      Master Bedroom
      EAST 35                 (35 is the bathroom)
      NORTHEAST 36            (36 is the closet)
      SPECIAL 50              <-- Special goes to room 50 (cavern)
      KEY 223                 <-- Special activated by touching mirror
      END_ROOM

      NOUN 223
      Mirror
      Strange                 (isn't there a better adjective?)
      There is a wall-size mirror here.
      LOCATION 34             (in the Master Bedroom)
      rem: the player finds this mirror in the master bedroom,
      rem: and gets to the Cavern by touching it.  The player
      rem: can only return if s/he has the magic amulet, and
      rem: will need the soap from the bathroom to kill the
      rem: demon on the bridge.
      UNMOVABLE               (not very useful if the player can take it!)
      PUSHABLE                <-- Here's how we'll activate the special
      END_NOUN

Below is an example of a badly-commented definition:

      ROOM 34
      Master Bedroom
      WEST 33                 (33 is the hallway)
      (If the player decides to enter the bathroom to the
      west, s/he will find the 32 gold pieces.)
      EAST 35                 (35 is the bathroom)
      NORTHEAST 36            (36 is the closet)
      SPECIAL 50              <-- Special goes to room 50 (cavern)
      KEY 223                 <-- Spec.activated by touching mirror
      (The player gets to the mystic cavern by means of a
      key special, activated by noun 233)
      END_ROOM

In the above example, the second full comment line begins with the keyword
"WEST" and contains the number 32, so AGT might decide that WEST should
lead to room 32, changing the game! The last line before the END_ROOM could
confuse AGT and redefine the key number (to 233).  That comment line is
also plainly incorrect, since it says "233" instead of "223."

                                                                             61

CREATING YOUR SOURCE DATA FILES WITH WORD PROCESSORS
      
When creating your source data files for your own AGT game, you must use a
text editor or word processor which creates plain ASCII or TEXT files with
a true carriage return at the end of each line.  Lines longer than 80
characters, WordStar or WordPerfect document files, will cause AGT to
abort!  The best rule-of-thumb is to use the MS-DOS "TYPE" command to view
the file.  If it looks normal, it's probably OK for AGT.  If words split at
the end of the line and strange characters appear, it's probably not OK for
AGT.

If you are using a Macintosh or Atari ST, your word processor or text
editor will have an option to save the file as an ASCII or TEXT file with
real carriage returns (sometimes called "line breaks") and without any
embedded "formatting" characters.  This is the option you should use.  For
example, if you are using Microsoft Word on the Macintosh, you would select
"SAVE AS" from the File Menu, then click the button that is labeled "File
Format...", then select the option that is says "Text Only With Line
Breaks."  Or another example -- if you are using MacWrite on the Macintosh,
you would select "SAVE AS" from the File Menu, then click the button that
is labeled "Text Only."  Other word processor will have similar options
when you save your game source files.


CREATING A FINAL COMPILED VERSION

In order to compile or create a finished adventure from your source files,
you will need to put the following files on a new, formatted disk:

      COMPILE.EXE     is the AGT program that converts your AGT "source"
                      files into the "compiled" or final files needed to play
                      the adventure.

      *.DAT           e.g., CRUSADE.DAT.  Files with the extension (suffix)
                      .DAT are source data files read by the COMPILE.EXE
                      program when it is running.

      *.CMD           e.g., CRUSADE.CMD.  Each file with the extension .CMD
                      is a source data file containing a set of special meta-
                      language commands for a corresponding game in a .DAT
                      file.  The use of a *.CMD file is unique to
                      Professional Level adventure games.  Games that do not
                      use these Professional Level features (such as, the
                      original GAGS games) would not have a *.CMD file.

                                                                             62

      *.MSG           e.g., CRUSADE.MSG.  Each file with the extension .MSG
                      is a source data file containing a set of special
                      messages for a corresponding game in a .DAT file.  The
                      use of a *.MSG file is unique to Professional Level
                      adventure games.  Games that do not use these Profes-
                      sional Level features (such as, the original GAGS
                      games) would not have a *.MSG file.

After these are on a new, formatted disk, you should enter the command
"COMPILE GameName", e.g., "COMPILE CRUSADE".  After a few minutes, AGT will
pause and give you a message about how much space there is on your disk
compared to how much space you need for the "final" or "compiled" version
files.  If you don't have enough space, the program will suggest you put in
a clean (already formatted) disk, before it writes the final files.


AGTNUM

William D. Martinson has written an excellent utility program for IBM AGT
users that can help manage all of the various numbers in the various AGT
game source files.  For example, using AGTNUM, it is possible to substitute
a descriptive "label" whenever one would normal use a number, such as:

      ROOM {sickbay}
      Sickbay
      EXIT {corridor}
      SOUTH {corridor}
      NORTH {operating room}
      END_ROOM

      ROOM_DESCR {sickbay}
      This is the sickbay, where the regulars are cured of all their ails
      and the extras meet slow, painful deaths.  The operating room is to
      the north.  The exit to the south leads to the corridor.
      END_ROOM_DESCR

In addition, AGTNUM has a number of other capabilities they can make
developing an AGT game easier.  See the separate documentation that comes
with AGTNUM on the disk for more details.

                                                                             63

PART 3: USING META-COMMANDS IN PROFESSIONAL LEVEL ADVENTURE GAMES


Before discussing meta-commands in detail, it is convenient to present a
quick overview of other changes in Professional Level games.  The principal
changes are the addition of custom user-defined verbs and Maximum_Score to
the .DAT file (NOTE: everything else about the .DAT files as previously
presented still applies in Professional Level games), the addition of a
.MSG file to hold your unique output messages, and the addition of a .CMD
file to hold your game's meta-commands.  Each of this will be presented
below in separate sections.


CUSTOM USER-DEFINED VERBS

Custom user-defined verbs are defined very much like "Verb Synonyms".  For
example, the following lines in the .DAT file will define several new verbs
(and synonyms):

      VERB
      Dummy_Verb1 KISS HUG LOVE CARESS
      Dummy_Verb2 GO CLIMB CROSS
      Dummy_Verb3 CUT CHOP BREAK CRACK BUST
      Dummy_Verb4 JUMP LEAP
      Dummy_Verb5 SEARCH FIND
      END_VERB

AGT adds 50 "dummy verbs" (Dummy_Verb1 ...  Dummy_Verb50) to the list of
valid verbs.  These dummy verbs are then redefined as if they had synonyms
in statements like the ones above.  These user-defined verbs are then used
in meta-commands to specify new conditional tests and appropriate actions. 
For example, the following meta-commands (in the .CMD file) would allow the
player to CLIMB a tree and to CROSS a bridge:

      COMMAND CLIMB TREE
      InRoom 208 (* sturdy oak tree *)
      GoToRoom 36 (* in branches at top of oak tree *)
      PrintMessage 43 (* You climb up to the top of the tree. *)
      DoneWithTurn
      END_COMMAND

      COMMAND CROSS BRIDGE
      AtLocation 23 (* West side of bridge *)
      GoToRoom 24 (* East side of bridge *)
      PrintMessage 44 (* You walk across the bridge to the other side. *)
      DoneWithTurn
      END_COMMAND

                                                                             64

      COMMAND CROSS BRIDGE
      AtLocation 24 (* East side of bridge *)
      GoToRoom 23 (* West side of bridge *)
      PrintMessage 44 (* You walk across the bridge to the other side. *)
      DoneWithTurn
      END_COMMAND

The above meta-commands could also have been done by CHANGE_LOCATION
specials.  However, custom verbs and meta-commands can also be used to
create more unusual situations, like these meta-commands for processing the
user's input to KISS or HUG something:

      COMMAND KISS PRINCESS
      InRoom 305 (* Princess *)
      AtLocation 99 (* Bridal Suite of palace *)
      PrintMessage 45 (* The princess melts into your strong arms, etc. *)
      PlusScore 25 (* Bonus for Kiss *)
      WinGame (* Win the game *)
      DoneWithTurn
      END_COMMAND

      COMMAND KISS PRINCESS
      InRoom 305 (* Princess *)
      NOT AtLocation 99 (* Not in Bridal Suite of palace *)
      PrintMessage 46 (* The princess pushes you away coyly, "Not here!" *)
      DoneWithTurn
      END_COMMAND

      COMMAND KISS TROLL
      InRoom 307 (* Ugly Troll *)
      PrintMessage 47 (* The troll kills you! *)
      KillPlayer (* That will teach you to KISS THE TROLL!! *)
      DoneWithTurn
      END_COMMAND

      COMMAND KISS ANY
      NOUNpresent (* NOUN (whatever it is) is here *)
      PrintMessage 48 (* You try to $verb$ the $noun$ for awhile. *)
      MinusScore 10 (* penalty for sick mind *)
      DoneWithTurn
      END_COMMAND

      COMMAND KISS ANY
      PrintMessage 49 (* The $adjective$ $noun$ isn't here! *)
      MinusScore 10 (* penalty for sick mind *)
      DoneWithTurn
      END_COMMAND

Meta-commands are processed in the order encountered in the .CMD file, so
the last two KISS ANY commands represent "default" commands and would be
activated only if you weren't trying to KISS, HUG, etc. the PRINCESS or the
TROLL.  For example, if you gave the input "KISS THE BLARNEY STONE", the

                                                                             65

game would respond with "You try to kiss the stone for a while" (Message
number 48 in the .MSG file) or "The blarney stone isn't here!" (Message
number 49) depending upon if the Blarney stone is present at your current
location or not.


MAXIMUM_SCORE

AGT allows the score to be manipulated via meta-language commands.  For
example, using meta-language commands, one could adjust the score whenever
the player:

      -- Accepts a hint
      -- Solves a particularly difficult puzzle
      -- Gives the correct answer to a riddle
      -- Performs a daring and/or noble act

The score can be manipulated either positively or negatively in this way.

Since in AGT you may add (or subtract) points from your score via your
deeds, the maximum score for the game will often be different from the sum
of the scores for visiting rooms and possessing objects.  In this
situation, you will need to specify a maximum score for the game in the
.DAT file.  For example, to have a maximum score of 350 points for the game
you would put the following statement in the game's .DAT file:

      MAXIMUM_SCORE 350


.MSG -- MESSAGE FILES

A file with the suffix of .MSG can contain up to 250 messages that are used
by various meta-language commands.  The format for each message is
straight-forward text as follows:

      MESSAGE 87
      As you $verb$ into the microphone, the security door slides open
      noiselessly.  You hurry into the vault.  The door closes behind you.
      END_MESSAGE

The messages need not be in numerical order, but it helps for debugging.

In any message, the game designer can use $VERB$, $NOUN$, $ADJECTIVE$,
$PREPOSITION$, $OBJECT$ and $NAME$ wherever he wants to have the original
verb, the noun, the noun's adjective, the preposition, the objective of the
preposition or the name of the person the command is addressed to (if any)
echoed back in a message.  $VERB$ uses the original verb which is input by
the player, not the verb for which it may be a synonym, e.g., if SPEAK is a
synonym for TALK and you input the verb SPEAK, the above MESSAGE 87 would
output "As you speak into the microphone..."

                                                                             66
IMPORTANT NOTE:  The $-words are case-sensitive.  For example, if you use
$NAME$, you will get the name echoed back to the player in the game in all
caps.  If you use $Name$, you will get the first letter of the name
capitalized and the remainder in lower case.  If you use $name$, you will
get the name displayed in all lower case letters.  These same case rules
also apply to the other $-words, i.e., $Verb$ will cause the verb to be
repeated back with its first letter capitalized and the other letters lower
case.

A TYPICAL GAME TURN

                                                                             67

                   __________________________________
        _________>|     Get Player's Input Command   |<_________
       |          |__________________________________|          |
       |                            |                           |
       |                            V                           |
       |           __________________________________           |
       |          | Parse into Addressee's Name (if  |          |
       |          | any), then Noun, Verb, Prep, Obj |          |
       |          |__________________________________|          |
       |                            |                           |
       |                            V                           |
       |                        __________               _______|______
       |                       |   Any    |  YES        |    Give      |
       |                       |  Errors  |____________>|    Error     |
       |                       |    ?     |             |   Message    |
       |                       |__________|             |______________|
       |                            |  NO
       |                            V
       |                        __________
       |                       |   Any    |
       |                       |  Meta-   | NO
       |                       | Language |_______________
       |                       | Commands |               |
       |                       |    ?     |               |
       |                       |__________|               |
       |                            |  YES                |
       |                            V                     |
       |           __________________________________     |
       |          |  Do meta-commands for ANY Words  |    |
       |          |__________________________________|    |
       |                            |                     |
       |                            V                     |
       |                        __________                |
       |                  YES  |   All    |               |
       |<______________________|  Done    |               |
       |                       |    ?     |               |
       |                       |__________|               |
       |                            | NO                  |
       |                            V                     |
       |           __________________________________     |
       |          | Do meta-commands for Input Words |    |
       |          |__________________________________|    |
       |                            |                     |
       |                            V                     |
       |                        __________                |
       |                  YES  |   All    |               |
       |<______________________|  Done    |               |
       |                       |    ?     |               |
       |                       |__________|               |
       |                            | NO                  |
       |                            V                     |
       |           __________________________________     |
       |          | Do Standard AGT routine for Verb |<___|
       |          |__________________________________|
       |____________________________|

                                                                             68

The meta-command boxes shown above are for Professional Level AGT games
only.

Now for a brief description of what these meta-command boxes do in an AGT
game.  The first meta box represents the process of testing for conditions
and performing various actions that do not depend on the player having
given a specific Addressee-Verb-Noun-Object combination, i.e., conditions
and actions for ANY words.  These kinds of situations are typically
"random" events, such as, (1) having a dwarf appear in the room and throw
an axe at the player, or (2) having a bear (that the player has befriended)
follow him into a new room, or (3) having a voice boom out an announcement
that "The Cave will close in 25 turns", or (4) having the player die
because of some random event (e.g., falling into a pit).  During each turn,
these ANY-words meta-commands are checked to see if the commands'
conditions are true and (if true) the meta-commands' designated actions are
taken.  This ANY-words process occurs before any specific
vocabulary-dependent meta-commands are executed.  Often, the results of
these ANY-words events will make subsequent actions unnecessary and/or
inappropriate.  For example, if a player dies a horrible death by a random
dwarf attack, finishing the player's specific command like GET GOLD or
EXAMINE BOOK is certainly inappropriate.

Here are a few examples of typical ANY Meta-Commands:

      COMMAND ANY
      Present 210 (* Blazing torch is here *)
      CounterGT 2 75 (* Torch has been lit for at least 75 turns *)
      PrintMessage 21 (* Your torch is flickering and growing weaker *)
      CounterEquals 2 100 (* Torch has been lit for 100 turns *)
      PrintMessage 22 (* The torch finally goes out! *)
      TurnCounterOFF 2 (* Torch has gone out, so turn torch counter OFF *)
      SwapLocations 210 211 (* swap blazing torch for unlit torch *)
      END_COMMAND

      COMMAND ANY
      NOT Present 312 (* Angry guard is not in room (yet) *)
      Chance 10 (* 10 % chance of guard appearing *)
      PutInCurrentRoom 312 (* put guard in room *)
      PrintMessage 23 (* An angry guard suddenly storms into the room! *)
      END_COMMAND

      COMMAND ANY
      FlagON 5 (* Flag 5 is ON if player has befriended parrot *)
      PutInCurrentRoom 306 (* Once befriended, parrot stays with player *)
      VerbIsDirection (* Player is going to new room *)
      PrintMessage 24 (* The parrot flies after you and lands nearby. *)
      END_COMMAND

                                                                             69

      COMMAND ANY
      InRoom 306 (* The parrot is here *)
      FlagOFF 4 (* Parrot is thirsty if Flag 4 is OFF *)
      Chance 5 (* 5 % chance of parrot talking *)
      PrintMessage 25 (* The parrot squawks "Polly wants a beer!" *)
      END_COMMAND

      COMMAND ANY
      InRoom 308 (* A vampire bat is here *)
      Chance 5 (* 5 % chance of being bitten *)
      PrintMessage 26 (* The vampire bat bites you on the neck!! *)
      KillPlayer (* Too bad, but vampire bat bites are fatal! *)
      DoneWithTurn (* No further process for this turn *)
      END_COMMAND

If the ANY-words meta-commands have not drastically changed the player's
status in the game, then specific Addressee-Verb-Noun-Object combination
meta-commands are tested and (if the conditions are true) the designated
actions are taken.  Using these meta-commands is the way that the game
designer can use unique verbs (that are not predefined in AGT).  For
example, the game designer could specify a meta-command for KISS PRINCESS
that would first check that the princess was in the room, and (if she was)
print a message like "The princess rudely pushes you away, straightens her
crown and loudly says, 'Stop the hanky-panky, buzzard breath!'"  The word
ANY may be substituted for the Verb, or the Noun, or the Object in a
meta-command.  For example, a meta-command for ATTACK ANY might be used to
specify a "default" response for the verb ATTACK, such as, printing a
message like "Don't be ridiculous, $verb$ing the $noun$ is really sick!" 
If the player entered the command ATTACK THE DOOR, the response would be
"Don't be ridiculous, attacking the door is really sick!"

Meta-commands can also be used to supplement or replace standard verb
processing.  For example, a meta-command could be used for verbs like READ,
GET, EAST, etc.  This type of substitution of meta-commands for standard
verbs could be used to (1) cause a key to fall out of a book the first time
the player gave the command to GET BOOK, (2) cause a player to go into a
hallucinatory state (i.e., a new room) whenever he gives the command DRINK
THE STRANGE LIQUID, or (3) cause a player to fall to his death on the rocks
far below if he gives the command NORTH (where there is a cliff to the
north in the current room).

If after doing both the ANY-words and the specific vocabulary meta-command
processing for a specific game turn, the player is still alive and further
AGT command processing is still appropriate, then the usual routine for the
player's verb is executed (if the input VERB is a standard AGT verb).  This
will be the way that the most of the player's inputs will be handled! 
Remember, most player commands in a typical adventure game deal with
manipulating items (GET, DROP, EXAMINE, READ, etc.) and traveling from room
to room (NORTH, SOUTH, UP, EXIT, etc).  Standard Level AGT handles these
types of commands quite nicely, and there will seldom be a need for
meta-commands for this type of typical player input.

                                                                             70

INTRODUCTION TO META-COMMANDS

Meta-commands are specified in the .CMD file.  The .CMD file can hold up to
400 meta-commands.  This capacity will enable the game designer to develop
some very sophisticated adventure games -- especially since the a majority
of a player's input will not require any meta-commands at all.

THE FORMAT OF META-COMMANDS

A typical meta-command in the .CMD file might look like this:

      COMMAND BREAK LOCK
      InRoom 208 (* Oak door with iron lock *)
      NOT InRoom 307 (* Evil Wizard is not in room *)
      IsCarrying 223 (* Battle Axe *)
       OR
      Present 246 (* Large Two-handed Sword *)
      VariableGT 7 90 (* Player has enough strength to swing sword *)
      FlagON 3 (* Sword has been pulled free from stone *)
       OR
      IsCarrying 221 (* Iron Mace *)
      VariableGT 7 50 (* Player has enough strength to swing mace *)
      SwapLocations 208 209 (* Swap locked oak door with open doorway *)
      PrintMessage 86 (* Your blows break the lock and door swings open *)
      ChangePassageway 1 25 (* open passage North (Dir 1) to room 25 *)
      DoneWithTurn (* No further process for this turn *)
      END_COMMAND

Each meta-command begins on a separate line with the keyword COMMAND. 
Following this is the input phrase for which this meta-command applies. 
The input phrase will be parsed, so you can use extra words for clarity. 
After being parsed, AGT will only remember the ADDRESSEE (if there is one),
the VERB, the NOUN and the OBJECT of the COMMAND.  If one of these is
missing, there is an implied ANY for the missing item.  For example, the
"BREAK LOCK" above is missing an OBJECT (and a preposition), so an implied
OBJECT of ANY is recorded for this COMMAND.  Because of this implied object
of ANY, this meta-COMMAND would be considered for any of the following
player inputs:

      BREAK LOCK
      BREAK THE LOCK WITH MACE
      BREAK LOCK WITH THE LARGE SWORD
      BREAK LOCK WITH ROCK (will not produced desired result)
      BREAK LOCK WITH DWARF'S HEAD (will not produced desired result)

If the COMMAND is an ANY meta-command, the word ANY will be the only word
follow the word COMMAND.  The end of the meta-command is signalled by
END_COMMAND on a separate line.

Between COMMAND and END_COMMAND are a series of conditional tests and
actions to be performed.  Each condition or action appears on a separate
line.  The first word of the action or condition line is the "Token", or

                                                                             71

abbreviation for the action or condition.  AGT allows 169 such tokens.
These tokens are a short-hand description of what condition is being tested
or what action is to be performed.  The tokens are normally shown with each
of the separate words of the short-hand description capitalized, e.g. 
PrintMessage.  This is only for better readability.  Internally, AGT does
not distinguish between upper and lower case in tokens.

There may be some numerical parameters on the line following the token. 
The number of parameters varies from none to two depending upon the
specific token.  For example, the token "KillPlayer" has no numerical
parameters; the token "PrintMessage" requires one numerical parameter
(i.e., the number of the message to be printed); the token "SwapLocations"
requires two numerical parameters (i.e., the two item numbers of the items
to have their locations switched).  Following the parameters (if any) on
the line is space for comments.  It is recommended that meta-commends be
very well commented and that the comments be written as the meta-commands
are first written.  Don't try to document them afterwards -- because you'll
never get around to really doing it!  For added clarity, comments should be
set off by some type of delimiter, such as, "(*", "*)" or "{", "}" or a
preceding ";".

If a conditional token is preceded on the line with the word "NOT", the
sense of the conditional test is reversed, i.e., NOT InRoom 307 tests that
creature number 307 (the evil wizard) is NOT in the current room.

The token OR may be used to connect two or more separate conditional tests
within a meta-command.  The overall test will be TRUE if any of the
individual OR conditions is TRUE.  In the above example, the sequence

      IsCarrying 223 (* Battle Axe *)
       OR
      Present 246 (* Large Two-handed Sword *)
      VariableGT 7 90 (* Player has enough strength to swing sword *)
      FlagON 3 (* Sword has been pulled free from stone *)
       OR
      IsCarrying 221 (* Iron Mace *)
      VariableGT 7 50 (* Player has enough strength to swing mace *)

tests if the player is carrying or has access to one (or more) of the heavy
weapons which is capable of breaking the lock on the door.

If there isn't an OR token between two conditions, there is an implied AND
condition between successive conditions.  The end of the series of OR's is
determined when AGT encounters the first Action token following the first
OR.  For example, the above meta-command might be rewritten in
pseudo-PASCAL as:

                                                                             72

     IF (Verb = 'BREAK') AND (Noun = 'LOCK') THEN  (* "BREAK LOCK" *)
        IF InRoom(208) THEN  (* Locked oak door is here *)
          IF (NOT InRoom(307)) THEN  (* Wizard not here *)
            IF IsCarrying(223)  (* Player has means to break door *)
               OR (Present(246) AND (Variable[7] > 90) AND FlagON[3])
               OR (IsCarrying(221) AND (Variable[7] > 50)) THEN
                 BEGIN
                   SwapLocations(208,209);(* Swap open door for locked *)
                   PrintMessage(86);  (* Print appropriate message *)
                   ChangePassageway(1,25);  (Open way north to room 25 *)
                   DoneWithTurn := TRUE;  (* Nothing more for this turn *)
                 END;

When processing a meta-command, AGT starts at the first action or condition
and continues to process each token until one of the conditions within the
meta-command is not met, i.e., it is FALSE, then AGT skips to the next
meta-command within the .CMD file.  For example, consider the following:

      COMMAND ANY
      Present 210 (* Blazing torch is here *)
      CounterGT 2 75 (* Torch has been lit for at least 75 turns *)
      PrintMessage 21 (* Your torch is flickering and growing weaker *)
      CounterEquals 2 100 (* Torch has been lit for 100 turns *)
      PrintMessage 22 (* The torch finally goes out! *)
      TurnCounterOFF 2 (* Torch has gone out, so turn torch counter OFF *)
      SwapLocations 210 211 (* swap blazing torch for unlit torch *)
      END_COMMAND

In this meta-command, Counter number 2 is used to keep track of the number
of turns that the torch has been blazing.  If the blazing torch isn't being
carried by the player or in the current room, the very first condition is
FALSE and AGT would skip ahead to the next meta-command -- i.e., no further
tokens in this meta-command would be considered.  However, if the blazing
torch was present in the room, AGT would consider the second condition,
specifically, if the torch has been blazing for more than 75 turns.  If it
has, then the next token would cause message 21 to be printed.  Then the
next token would test if the torch has been blazing for exactly 100 turns. 
If it hasn't, then AGT skips ahead to the next meta-command in the .CMD
file.  If the torch has been blazing for exactly 100 turns, then the last
three tokens (all action tokens) are processed and message 22 is printed,
the blazing torch counter is turned OFF, and an unlit torch (noun number
211) is swapped for the blazing torch (noun number 210).  For example, the
above meta-command might be rewritten in pseudo-PASCAL:

                                                                             73

     IF (Verb = 'ANY') THEN  (* ANY and ALL commands *)
        IF Present(210) THEN  (* Blazing torch *)
          IF (Counter[2] > 75) THEN  (* Burning for more than 75 turns *)
            BEGIN
              PrintMessage(21);  (* The torch is growing weaker. *)
              IF (Counter[2] = 100) THEN  (* Burning exactly 100 turns *)
                BEGIN
                  PrintMessage(22);  (* The torch goes out.  *)
                  TurnCounterOFF(2);  (* Turn burn counter off *)
                  SwapLocations(210,211);  (* Swap for unlit torch *)
                END;
            END;


META-COMMANDS CONDITIONAL TESTS

The are a total of 90 separate condition tokens in AGT.  Since each of this
conditions may be prefaced by a NOT condition, there are actually a total
of 180 conditional tests possible within a meta-command.  These conditional
tests divide into several logical groups:

       - Tests about the player's status and/or condition
       - Tests about the status/condition of specific item(s)
       - Tests about the status/condition of the current NOUN
       - Other miscellaneous tests

Let's consider each of these logical groups in order.  First, tests about
the player's status and/or Condition:

                          ____________________
 ________________________|  PLAYER CONDITIONS |_______________________________
|                        |____________________|                               |
|                      NUMBER/TYPES                                           |
| TOKEN NAME           OF PARAMETERS              EXPLANATION                 |
|_____________________________________________________________________________|
| AtLocation          |1|Location#  | Player is located at room Location#     |
| AtLocationGT        |1|Location#  | Player is in room greater than Location#|
| AtLocationLT        |1|Location#  | Player is in room less than Location#   |
| FirstVisitToRoom    |0|None       | First visit to current room             |
| IsCarryingSomething |0|None       | Player is carrying something            |
| IsCarryingNothing   |0|None       | Player is carrying nothing              |
| IsCarryingTreasure  |1|Points#    | Player is carrying at least one item    |
|                     | |           |    that is worth at least Points#       |
| IsWearingSomething  |0|None       | Player is wearing something             |
| IsWearingNothing    |0|None       | Player is wearing nothing               |
| LoadWeightEquals    |1|Number     | Player's load weighs equals Number      |
| LoadWeightGT        |1|Number     | Player's load weighs more than Number   |
| LoadWeightLT        |1|Number     | Player's load weighs less than Number   |
| NewLife             |0|None       | Player has just been resurrected or     |
|                     | |           |    start of game                        |
|_____________________|_|___________|_________________________________________|

                                                                             74

All these tokens test conditions about the player current status, i.e.,
where he is/isn't located, if he is/isn't wearing or carrying something,
and if his current load weighs a certain amount.  All these conditions
are obvious except for

      IsCarryingTreasure 10 (* Has something worth at least 10 points *)

which might be used to test whether it is appropriate to have some type
of thief (randomly) rob the player of his valuables.

The second group of conditions test the status of various items or
nouns:

                          ____________________
 ________________________| ITEM(S) CONDITIONS |_______________________________
|                        |____________________|                               |
|                      NUMBER/TYPES                                           |
| TOKEN NAME           OF PARAMETERS              EXPLANATION                 |
|_____________________________________________________________________________|
| Present             |1|Item#      | Item# is in room, carried or worn       |
| IsWearing           |1|Item#      | Item# is being worn                     |
| IsCarrying          |1|Item#      | Item# is being carried                  |
| IsNowhere           |1|Item#      | Item# is located NOWHERE (in room 0)    |
| IsSomewhere         |1|Item#      | Item# is located somewhere (not in 0)   |
| InRoom              |1|Item#      | Item# is located in current room        |
| IsLocated           |2|Item# Loc# | Item# is located in room Location#      |
| Together            |2|Itm1# Itm2#| Itm1# and Itm2# are in same place       |
| IsON                |1|Item#      | Item# is ON                             |
| IsOFF               |1|Item#      | Item# is OFF                            |
| IsOpen              |1|Item#      | Item# is Open                           |
| IsClosed            |1|Item#      | Item# is Closed                         |
| IsLocked            |1|Item#      | Item# is Locked                         |
| IsUnLocked          |1|Item#      | Item# is UnLocked                       |
| IsEdible            |1|Item#      | Item# is Edible                         |
| IsDrinkable         |1|Item#      | Item# is Drinkable                      |
| IsPoisonous         |1|Item#      | Item# is Poisonous                      |
| IsMovable           |1|Item#      | Item# is Movable                        |
| IsGroupMember       |1|Item#      | Item# is a member of the group          |
| SomethingInside     |1|Item#      | Item# has something inside it.  Item#   |
|                     | |           |   can represent a ROOM, NOUN or CREATURE|
|_____________________|_|___________|_________________________________________|

All but two of the above tokens require one parameter: the number of the
item for which the conditional test is being considered.  Examples of
these two exceptions are:

      IsLocated 205 34 (* Tests if Noun number 205 is in Room 34 *)
      Together 256 257 (* Tests if Nouns 256 and 257 are together *)

The next group of conditional tokens is similar to the above except that
they are tests for the current NOUN which has been input, not a specific
item:

                                                                             75

                          ____________________
 ________________________|   NOUN CONDITIONS  |_______________________________
|                        |____________________|                               |
|                      NUMBER/TYPES                                           |
| TOKEN NAME           OF PARAMETERS              EXPLANATION                 |
|_____________________________________________________________________________|
| NOUNPresent         |0|None       | NOUN is in room, carried or worn        |
| NOUNIsWearing       |0|None       | NOUN is being worn                      |
| NOUNIsCarrying      |0|None       | NOUN is being carried                   |
| NOUNIsNowhere       |0|None       | NOUN is located NOWHERE (in room 0)     |
| NOUNIsSomewhere     |0|None       | NOUN is located somewhere (not room 0)  |
| NOUNInRoom          |0|None       | NOUN is located in current room         |
| NOUNIsLocated       |1|Location#  | NOUN is located in room Location#       |
| NOUNIsON            |0|None       | NOUN is ON                              |
| NOUNIsOFF           |0|None       | NOUN is OFF                             |
| NOUNIsOpen          |0|None       | NOUN is Open                            |
| NOUNIsClosed        |0|None       | NOUN is Closed                          |
| NOUNIsLocked        |0|None       | NOUN is Locked                          |
| NOUNIsUnLocked      |0|None       | NOUN is UnLocked                        |
| NOUNIsEdible        |0|None       | NOUN is Edible                          |
| NOUNIsDrinkable     |0|None       | NOUN is Drinkable                       |
| NOUNIsPoisonous     |0|None       | NOUN is Poisonous                       |
| NOUNIsMovable       |0|None       | NOUN is Movable                         |
| NOUNpointsEquals    |1|Number     | NOUN's points equal Number              |
| NOUNpointsGT        |1|Number     | NOUN's points are greater than Number   |
| NOUNpointsLT        |1|Number     | NOUN's points are less than Number      |
| NOUNweightEquals    |1|Number     | NOUN's weight equals Number             |
| NOUNweightGT        |1|Number     | NOUN's weight is greater than Number    |
| NOUNweightLT        |1|Number     | NOUN's weight is less than Number       |
| NOUNIsCreature      |0|None       | NOUN is a creature, rather than Noun    |
| NOUNIsNumber        |1|Number     | NOUN's num is Number, e.g., NOUN is     |
|                     | |           |    number 235                           |
|_____________________|_|___________|_________________________________________|

The above tokens are especially useful if the game designer wants to
create his own unique standard default responses to situations, rather
than relying on the normal AGT responses.  For example, below are new
default responses for the verb GET:

      COMMAND GET ANY
      NOUNInRoom (* NOUN is in current room *)
      NOUNIsMovable (* NOUN can be moved *)
      LoadWeightLT 90 (* carrying less than 90 pounds *)
      NOUNweightLT 11 (* NOUN is less than 11 pounds *)
      GetNOUN (* Add NOUN to items being carried *)
      PrintMessage 1 (* You add the $noun$ to your load. *)
      DoneWithTurn (* Nothing more required for this turn *)
      END_COMMAND

                                                                             76

      COMMAND GET ANY
      NOUNIsCarrying (* NOUN is currently being carried *)
      PrintMessage 2 (* You already have it, Stupid! *)
      DoneWithTurn (* Nothing more required for this turn *)
      END_COMMAND

      COMMAND GET ANY
      NOT NOUNPresent (* NOUN is NOT present *)
      PrintMessage 3 (* The $noun$ isn't here, you oaf! *)
      DoneWithTurn (* Nothing more required for this turn *)
      END_COMMAND

      COMMAND GET ANY
      NOT NOUNIsMovable (* NOUN cannot be moved *)
      PrintMessage 4 (* Sorry, but the $noun$ cannot be moved! *)
      DoneWithTurn (* Nothing more required for this turn *)
      END_COMMAND

      COMMAND GET ANY
      NOUNIsMovable (* NOUN can be moved *)
      LoadWeightGT 89 (* carrying 90 pounds or more already *)
      PrintMessage 5 (* Your load is too heavy to carry the $noun$. *)
      DoneWithTurn (* Nothing more required for this turn *)
      END_COMMAND

A series of COMMANDS like these is processed sequentially by their order
of appearance in the .CMD file.  As a result, the COMMANDs order is very
important!  For example, if the player gave the input GET STATUE and the
statue was not in the room and was also not movable, the error message
"The statue isn't here, you oaf!" would be printed rather than "Sorry,
but the statue cannot be moved!" because of the order of their
respective COMMANDS above (or in the .CMD file).

The last group of conditional tokens is a catch-all:

                                                                             77


                      ____________________________
 ____________________|  MISCELLANEOUS CONDITIONS  |___________________________
|                    |____________________________|                           |
|                      NUMBER/TYPES                                           |
| TOKEN NAME           OF PARAMETERS              EXPLANATION                 |
|_____________________________________________________________________________|
| NamePresent         |0|None       | Addressee is present in current room    |
| NameIsNumber        |1|Number     | Addressee is Creature or Noun number    |
| ObjectPresent       |0|None       | Object is present                       |
| ObjectIsCreature    |0|None       | Object is a Creature                    |
| ObjectIsNumber      |1|Number     | Object is Creature or Noun number       |
| LightPresent        |0|None       | Current room has necessary light        |
| RoomNeedsLight      |0|None       | Current room needs a light              |
| FlagON              |1|Flag#      | Flag# is ON                             |
| FlagOFF             |1|Flag#      | Flag# is OFF                            |
| ScoreEquals         |1|Number     | Current score is equal to Number        |
| ScoreGT             |1|Number     | Score is greater than Number            |
| ScoreLT             |1|Number     | Score is less than Number               |
| NumberEquals        |1|Number     | Number input is equal to Number         |
| NumberGT            |1|Number     | Number is greater than Number           |
| NumberLT            |1|Number     | Number is less than Number              |
| AnswerIsCorrect     |0|None       | Last answer was correct                 |
| AnswerIsWrong       |0|None       | Last answer was wrong                   |
| TurnsEquals         |1|Number     | Number of turns is equal to Number      |
| TurnsGT             |1|Number     | Number of turns is greater than Number  |
| TurnsLT             |1|Number     | Number of turns is less than Number     |
| CounterEquals       |2|Ctr# Number| Counter# is equal to Number             |
| CounterGT           |2|Ctr# Number| Counter# is greater than Number         |
| CounterLT           |2|Ctr# Number| Counter# is less than Number            |
| VariableEquals      |2|Var# Number| Variable# is equal to Number            |
| VariableGT          |2|Var# Number| Variable# is greater than Number        |
| VariableLT          |2|Var# Number| Variable# is less than Number           |
| CompareVariables    |2|Var#1 Var#2| Variable#1 is less than Variable#2      |
| VariableChance      |2|Var# Number| Variable# is less than a random number  |
|                     | |           |    from 1 to Number                     |
| Chance              |1|Percent    | Odds percent, i.e., 10 % chance of TRUE |
| PromptForYES        |0|None       | Prompts for Y or N -- TRUE if Yes       |
| PromptForNO         |0|None       | Prompts for Y or N -- TRUE if No        |
| VerbIsDirection     |0|None       | Verb is movement or direction           |
|_____________________|_|___________|_________________________________________|

Just a few words of explanation about a couple of these.  PromptForYES
and PromptForNO cause the player to be queried and to respond by
entering a YES (or Y) or NO (or N) on the keyboard.  These conditions
are then TRUE or FALSE depending upon the what is entered.  These tokens
are particular useful when you want to ask the player a question that
requires a YES or NO answer like whether he would like a hint. 
AnswerIsCorrect and AnswerIsWrong are similar tokens for asking
questions which do not have YES and NO answers like asking a riddle.  An
example of how to ask a trivia question will be given later in this
document.

                                                                             78

The number referenced by the NumberEquals, NumberGT and NumberLT is a
number that the player inputs via the keyboard in response to a
GetNumberInput action token.  An example of this sequence of events will
be given later.

The game designer has 255 Flags (1 to 255) which can be tested for being
ON or OFF respectively by the FlagON and FlagOFF tokens.  There are 25
Counters (1 to 25) and 25 Variables (1 to 25) which can also be tested
by various tokens described above.  How to set these Flags, Counters and
Variables will be described in the section on ACTION tokens below.


META-COMMANDS ACTION TOKENS

There are a total of 79 separate action tokens in AGT.  These actions
divide into several logical groups:

      - Actions involving the player
      - Actions involving specific item(s), the NOUN or locations
      - Other miscellaneous actions

Let's consider each of these logical groups in order.  First, actions
involving the player:

                         ________________________
 _______________________|  PLAYER ACTION TOKENS  |____________________________
|                       |________________________|                            |
|                      NUMBER/TYPES                                           |
| TOKEN NAME           OF PARAMETERS              EXPLANATION                 |
|_____________________________________________________________________________|
| GoToRoom            |1|Location#  | Send player to Location#                |
| GoToRandomRoom      |2|Loc#1 Loc#2| Randomly pick a room between Loc#1 and  |
|                     | |           |    Loc#2 and send player to it          |
| GetIt               |1|Item#      | Item# is now being carried              |
| WearIt              |1|Item#      | Item# is now being worn                 |
| DropIt              |1|Item#      | Drop Item# into current room            |
| RemoveIt            |1|Item#      | Remove Item# and drop into room         |
| GetNOUN             |0|None       | NOUN is now being carried               |
| WearNOUN            |0|None       | NOUN is now being worn                  |
| DropNOUN            |0|None       | Drop NOUN into current room             |
| RemoveNOUN          |0|None       | Remove NOUN and drop into room          |
| DropEverything      |0|None       | Drop all items being carried            |
| RemoveEverything    |0|None       | Remove all items being worn             |
| KillPlayer          |0|None       | Make player dead at end of turn         |
|_____________________|_|___________|_________________________________________|

These actions are all straight-forward.


                                                                             79

A WORD OF WARNING:

When AGT encounters and processes an action token, it is done without
fanfare or logical checking.  For example, if the actions

      DropIt 204 (* Put the Rubber Ducky in the room *)
      WearNOUN (* Put on or Wear NOUN *)

are encountered, they are done without checking whether the player is
carrying the Rubber Ducky currently or if the NOUN is something that
might be logically worn. The game designer is warned that this kind of
logical checking before taking actions is his or her responsibility --
not AGT's!

The second group of actions involve items, nouns and locations:

                     ____________________________________
 ___________________|  ITEM/NOUN/LOCATION ACTION TOKENS  |____________________
|                   |____________________________________|                    |
|                      NUMBER/TYPES                                           |
| TOKEN NAME           OF PARAMETERS              EXPLANATION                 |
|_____________________________________________________________________________|
| PutInCurrentRoom    |1|Item#      | Put Item# in current room               |
| PutNOUNInCurrentRoom|0|None       | Put NOUN in current room                |
| RelocateAll         |2|Loc1# Loc2#| Relocate all items at Loc1# to Loc2#    |
| SendToRoom          |2|Item# Loc# | Put Item# in Location Loc#              |
| SendNOUNToRoom      |1|Location#  | Put NOUN in room Location#              |
| SendAllToRoom       |1|Location#  | Send all carried items to Location#     |
| SendTreasuresToRoom |2|Loc# Point#| Send all carried items whose            |
|                     | |           |    points > Point# to Loc#              |
| Destroy             |1|Item#      | Item# is now NOWHERE (in room 0)        |
| DestroyNOUN         |0|None       | NOUN is now NOWHERE (in room 0)         |
| SwapLocations       |2|Itm#1 Itm#2| Swap locations of Item#1 & Item#2       |
| SendToItem          |2|Itm#1 Itm#2| Put Itm#1 in location of Itm#2          |
| SendNOUNToItem      |1|Item#      | Put NOUN in location of Item#           |
| OpenIt              |1|Item#      | Item# is now open                       |
| CloseIt             |1|Item#      | Item# is now closed                     |
| LockIt              |1|Item#      | Item# is now locked                     |
| UnlockIt            |1|Item#      | Item# is now unlocked                   |
| OpenNOUN            |0|None       | NOUN is now open                        |
| CloseNOUN           |0|None       | NOUN is now closed                      |
| LockNOUN            |0|None       | NOUN is now locked                      |
| UnlockNOUN          |0|None       | NOUN is now unlocked                    |
| AddToGroup          |1|Item#      | Adds Item# to group                     |
| RemoveFromGroup     |1|Item#      | Removes Item# from group                |
| MoveTheGroup        |1|Location#  | Move group to Location#                 |
|_____________________|_|___________|_________________________________________|

Several of these deserve some explanation.  SendTreasureToRoom is useful
when the game designer wishes to have the player's current treasures or
valuables stolen or disappear.  For example:

                                                                             80

     SendTreasureToRoom 28 9 (* send valuables to room 28 *)

would cause any items that were being currently carried and had point
values of 10 or more to be sent to room 28.  Items being carried with
values of 9 or less would continue to be carried.  The conditional token
IsCarryingTreasure can be used to test whether such a "theft" is
appropriate.

The SwapLocations action token is very useful whenever the game designer
wishes to change the status or condition of an item.  For example, this
action can be used to replace a closed door with an open door, or to
replace an egg with egg shell pieces (when the player gives the input
BREAK EGG), or to replace a small plant with a larger plant (when the
player inputs the command WATER PLANT), or to replace a frog with a
handsome prince (when the player inputs KISS FROG).  A very useful and
powerful token!

The last group of actions do a variety of tasks:


                     _________________________________
 ___________________|   MISCELLANEOUS ACTION TOKENS   |_______________________
|                   |_________________________________|                       |
|                      NUMBER/TYPES                                           |
| TOKEN NAME           OF PARAMETERS              EXPLANATION                 |
|_____________________________________________________________________________|
| ShowScore           |0|None       | Show current SCORE                      |
| PlusScore           |1|Number     | Add Number to current SCORE             |
| MinusScore          |1|Number     | Subtract Number from current SCORE      |
| ShowInventory       |0|None       | Show current INVENTORY                  |
| ShowContents        |1|Number     | Show contents (if any) of entity Number |
| WaitForReturn       |0|None       | Print 'Hit RETURN' message and wait     |
| TimePasses          |0|None       | Show 'Time passes...' message           |
| Delay               |1|Number     | Delay for Number seconds                |
| ClearScreen         |0|None       | Clear screen                            |
| DescribeThing       |1|Number     | Describe thing Number (whatever)        |
| LookAtRoom          |0|None       | Cause a VERBOSE look at room            |
| Tone                |2|Hz Ms      | Makes a tone on speaker of Hz Hertz (440|
|                     | |           |  Hertz = A on piano) for Ms milliseconds|
| PrintMessage        |1|Number     | Print message Number in .MSG file       |
| RandomMessage       |2|Num1 Num2  | Randomly picks a message from Num1 to   |
|                     | |           |   Num2 in .MSG file and prints it       |
| BlankLine           |0|None       | Print a blank line                      |
| GetNumberInput      |2|Num1 Num2  | Prompt for player to input a Number     |
|                     | |           |   where Num1 <= Number <= Num2.         |
|                     | |           |   If Num1=Num2, then no range will be   |
|                     | |           |   given in prompt.                      |
| AskQuestion         |1|Question#  | Ask and get answer to question#         |
|_____________________|_|___________|_________________________________________|

                                                                             81

                ____________________________________________
 ______________|   MISCELLANEOUS ACTION TOKENS - CONTINUED  |_________________
|              |____________________________________________|                 |
|                      NUMBER/TYPES                                           |
| TOKEN NAME           OF PARAMETERS              EXPLANATION                 |
|_____________________________________________________________________________|
| ChangePassageway    |2|Dir# Loc#  | Create or close a passageway            |
|                     | |           |   from current_room to Loc# via Dir#.   |
|                     | |           |   Dir# = 1 = north...Dir # = 12 = exit. |
|                     | |           |   If Loc# = 0 then closes passageway.   |
|                     | |           |   If Loc# <> 0 then opens passageway    |
|                     | |           |   to room Loc# via direction Dir#.      |
|                     | |           |   Passageways are opened or closed at   |
|                     | |           |   both ends simultaneously!             |
| TurnFlagON          |1|Flag#      | Turn Flag# ON                           |
| TurnFlagOFF         |1|Flag#      | Turn Flag# OFF                          |
| ToggleFlag          |1|Flag#      | Toggle Flag#                            |
| TurnCounterON       |1|Counter#   | Turn Counter# ON -- sets to 1           |
| TurnCounterOFF      |1|Counter#   | Turn Counter# OFF -- sets to 0          |
| SetVariableTo       |2|Var# Number| Set Variable Var# to Number             |
| AddToVariable       |2|Var# Number| Add Number to Var#                      |
| SubtractFromVariable|2|Var# Number| Subtract Number from Var#               |
| AddVariables        |2|Var#1 Var#2| Add Var#2 and Var#1 and put answer      |
|                     | |           |   into Var#1                            |
| SubtractVariables   |2|Var#1 Var#2| Subtract Var#2 from Var#1 and put answer|
|                     | |           |   into Var#1                            |
| RandomVariable      |2|Var# Number| Set Var# to a random value between 0 and|
|                     | |           |   Number                                |
| MakeVarRoomNum      |1|Var#       | Set Var# to current room number         |
| MakeVarNounNum      |1|Var#       | Set Var# to number of current noun      |
| MakeVarObjectNum    |1|Var#       | Set Var# to number of current object    |
| GoToVariableRoom    |1|Var#       | Send player to room number in Var#      |
| SendToVariableRoom  |2|Num Var#   | Send Noun number num to room number     |
|                     | |           |   in Var#                               |
| GetVariableIt       |1|Var#       | Get noun number in Var#                 |
| PrintVariableMessage|1|Var#       | Print message number in Var#            |
| NounToVariable      |1|Var#       | Set Var# to literal value of noun       |
| ObjectToVariable    |1|Var#       | Set Var# to literal value of object     |
| WinGame             |0|None       | Player wins game at end of turn         |
| EndGame             |0|None       | Game ends at end of turn                |
| QuitThisCMD         |0|None       | Quit evaluating this CMD                |
| QuitAllCMDs         |0|None       | Finished with all meta-commands         |
| DoneWithTurn        |0|None       | All Done this turn -- get input next    |
| ReDirectTo          |0|None       | See explanation in manual.              |
|_____________________|_|___________|_________________________________________|


SPECIAL META-COMMAND SITUATIONS

There are some very powerful (and potentially confusing) actions above! 
Some words of explanation and some examples are in order.  Specific
topics to be covered below are: (1) Flags, (2) Counters, (3) Variables,

                                                                             82

(4) Number Input, (5) Asking and Answering Questions, (6) Dealing with
Multiple Nouns with the Same Name, (7) Handling the Contents of Various
Things, (8) Opening and Closing Passageways Between Rooms, and (9) Meta-
command Redirection.


FLAGS

The game designer has 255 Flags at his disposal.  They are turned on
with the TurnFlagON token, turned off with the TurnFlagOFF token and
toggled with the ToggleFlag token.  They are tested with the FlagON and
FlagOFF condition tokens.  The game designer should take great care in
selecting and documenting his use of Flags.  Always, explain what each
Flag stands for and what the ON and OFF conditions mean in comments at
the beginning of the .CMD file!  Whenever you change the condition of a
Flag explain what this new condition stands for in the game!

When the game starts, all Flags are OFF.  This fact can be used to test
if certain initial actions should be taken, such as, making sure the
flashlight's batteries are fresh.  When the game is SAVEd and RESTOREd
the condition of the Flags, Counters and Variables is also SAVEd and
RESTOREd.


DEBUG FLAG

There is a Flag number 0 which is used by AGT to toggle the debugging
mode of meta-commands.  When Flag 0 is ON then each meta-command being
considered will be output to the screen.  By giving the input command
SCRIPT you can also route this information to the printer.  This
capability can be invaluable when you are trying to fathom a complex
meta-command "bug".  The best way to use this capability in your game is
to define a custom verb like DEBUG in the verb synonym section of the
.DAT file and then define a meta-command like:

      COMMAND DEBUG
      ToggleFlag 0 (* Toggles meta-command Debug mode *)
      DoneWithTurn (* Finished with this turn *)
      END_COMMAND

Both the sample games CAVE and CRUSADE have this capability.  Try it in
one of those games to see how it works.


COUNTERS

There are 25 Counters (1 to 25) in AGT that can be turned ON with the
TurnCounterON token and turned OFF with the TurnCounterOFF token.  When
a counter is ON, it is automatically incremented at each turn of the
game.  When a counter is OFF, it is set to zero and is not incremented. 
The condition of these counters can be tested using the CounterEquals,
CounterGT and CounterLT conditional tokens.  Using counters is very

                                                                             83

useful for such things as keeping track of the number of turns (1) a
torch is lit, (2) a player has been underwater using an aqua-lung, or
(3) a time-bomb has been ticking.  The value of a counter can be printed
in a message by using #CTR5# (to print counter number 5).

The game designer's use of Counters should be very carefully commented
in the .CMD file!


VARIABLES

There are 25 Variables (1 to 25) in AGT that can be set to a specific
value with the SetVariableTo token and added to with the AddToVariable
token and subtract from with SubtractFromVariable token.  These
variables can also be set to a random value with the RandomVariable
token, and variables can be added together with the AddVariables, and
subtracted from one another using the SubtractVariables token.  The
condition of these variables can be tested using the VariableEquals,
VariableGT and VariableLT and VariableChance conditional tokens.  Using
variables is very useful for such things as keeping track of the number
of times (1) a player has asked for HELP, (2) a player has crossed a
certain rickety bridge, or (3) until a specific event happens (like the
cave closes or the lamp's batteries go out).  Other excellent uses of
variables are to keep track of various attributes the player may have
such as Strength, Health, Charisma, etc.  The value of a variable can be
printed in a message by using #VAR3# (to print variable number 3).

As an example, the following meta-commands in the .CMD file will (1)
initialize the flash batteries to last a total of 100 turns, (2)
decrement a variable for every turn the light is ON, (3) issue warnings
when the battery will last 20 turns or less, (4) "kill" the flashlight
when the batteries finally go out, (5) turn the flashlight ON and OFF
with the input commands LIGHT and EXTINGUISH.

      ; Comments
      ; Flag 1 is OFF at start of game and ON otherwise
      ; Flag 2 is OFF if the flashlight is OFF and ON if it is ON
      ; Variable 5 will count down the life of the battery
      ; Noun 200 is FlashLight in OFF condition
      ; Noun 201 is FlashLight in ON condition
      ; Noun 202 is FlashLight in DEAD condition

      ; ANY meta-command -- tried at each turn of game

      COMMAND ANY
      FlagOFF 1 (* First turn of game -- initialize Battery life *)
      SetVariableTo 5 100 (* Battery life set to 100 turns *)
      TurnFlagON 1 (* Initialization process is now over *)
      END_COMMAND

                                                                             84

      COMMAND ANY
      FlagON 2 (* Flashlight is turned ON *)
      SubtractFromVariable 5 1 (* Decrement Battery life count *)
      END_COMMAND

      COMMAND ANY
      FlagON 2 (* Flashlight is turned ON *)
      Present 201 (* No reason to give warning unless Flashlight here *)
      VariableGT 5 0 (* At least one more turn left in batteries *)
      VariableLT 5 21 (* Only a few more turns left in batteries *)
      PrintMessage 22 (* Flashlight will last only #VAR5# more turns! *)
      VariableEquals 5 20 (* Only print next message once *)
      PrintMessage 23 (* You had better save your batteries! *)
      END_COMMAND

      COMMAND ANY
      FlagON 2 (* Flashlight is turned ON *)
      VariableEquals 5 0 (* The batteries are finally dead! *)
      TurnFlagOFF 2 (* Turn it off for the last time! *)
      SwapLocations 201 202 (* Swap ON Flashlight for DEAD one *)
      Present 202 (* No reason to give message unless Flashlight here *)
      PrintMessage 24 (* The Flashlight's batteries are dead!! *)
      END_COMMAND

etc...  for other ANY meta-commands

      ; Specific Vocabulary meta-command -- tried only if WORDS match

      COMMAND LIGHT FLASHLIGHT
      Present 200 (* OFF flashlight is present *)
      TurnFlagON 2 (* Flashlight is turned ON *)
      SwapLocations 200 201 (* Swap OFF Flashlight for ON one *)
      PrintMessage 25 (* The flashlight is ON and shining brightly! *)
      DoneWithTurn (* Finished with this turn *)
      END_COMMAND

      COMMAND LIGHT FLASHLIGHT
      Present 201 (* ON flashlight is present *)
      PrintMessage 26 (* The flashlight is already ON, dummy! *)
      DoneWithTurn (* Finished with this turn *)
      END_COMMAND

      COMMAND LIGHT FLASHLIGHT
      Present 202 (* DEAD flashlight is present *)
      PrintMessage 27 (* Sorry, but the batteries are dead! *)
      DoneWithTurn (* Finished with this turn *)
      END_COMMAND

                                                                             85

      COMMAND EXTINGUISH FLASHLIGHT
      Present 201 (* ON flashlight is present *)
      TurnFlagOFF 2 (* Flashlight is turned OFF *)
      SwapLocations 200 201 (* Swap OFF Flashlight for ON one *)
      PrintMessage 28 (* The flashlight is now off! *)
      DoneWithTurn (* Finished with this turn *)
      END_COMMAND

      COMMAND EXTINGUISH FLASHLIGHT
      Present 200 (* OFF flashlight is present *)
         OR
      Present 202 (* DEAD flashlight is present *)
      PrintMessage 29 (* The flashlight is already OFF! *)
      DoneWithTurn (* Finished with this turn *)
      END_COMMAND

Needless to say, the game designer's use of Variables should be very
carefully commented in your .CMD file!


NUMBER INPUT

By using meta-commands it is possible to accept number input from the
player during the course of the game and to test the number he has
input.  An example of where such a capability might be appropriate is
having the player open a combination safe.  An example of use,
GetNumberInput 4 20 would cause the player to be prompted as follows:

      "What number (from 4 to 20) ? "

This prompt would be repeated until the player entered a number in the
correct range (i.e., an integer from 4 to 20).  If the game designer
didn't want to limit the input number to a specific range, both
parameters should be equal.  For example, GetNumberInput 0 0 would cause
the prompt to be:

      "What number ? "

Once input, the number can be tested by using the NumberEquals,
NumberGT, and NumberLT conditional tokens.

Another way that AGT will allow number input is as the Noun or Object
within an input command.  For example, let's say the player is in an
elevator and he needs to push a button corresponding to a floor. 
Commands like "PUSH 3" will be accepted by the AGT parser.  The Noun "3"
can then be assigned to a variable using the NounToVariable token,
tested using the VariableEquals token, then the player would be sent to
the appropriate floor.  For example, the following series of meta-
commands will enable the player to go to any one of four floors by
giving the correct command.

                                                                             86

      COMMAND PUSH ANY
      SetVariableTo 2 0 (* Set Variable #2 to 0 *)
      AtLocation 14 (* In Elevator *)
      NounToVariable 2 (* Set Variable #2 to floor number {if any} *)
      VariableEquals 2 1 (* Did player push 1? *)
      GoToRoom 21 (* Move player to 1st floor *)
      PrintMessage 121 (* The Elevator glides to #VAR2# and you exit. *)
      DoneWithTurn (* Finished with this turn *)
      END_COMMAND

      COMMAND PUSH ANY
      AtLocation 14 (* In Elevator *)
      VariableEquals 2 2 (* Did player push 2? *)
      GoToRoom 22 (* Move player to 2nd floor *)
      PrintMessage 121 (* The Elevator glides to #VAR2# and you exit. *)
      DoneWithTurn (* Finished with this turn *)
      END_COMMAND

      COMMAND PUSH ANY
      AtLocation 14 (* In Elevator *)
      VariableEquals 2 3 (* Did player push 3? *)
      GoToRoom 23 (* Move player to 3rd floor *)
      PrintMessage 121 (* The Elevator glides to #VAR2# and you exit. *)
      DoneWithTurn (* Finished with this turn *)
      END_COMMAND

      COMMAND PUSH ANY
      AtLocation 14 (* In Elevator *)
      VariableEquals 2 4 (* Did player push 4? *)
      GoToRoom 24 (* Move player to 4th floor *)
      PrintMessage 121 (* The Elevator glides to #VAR2# and you exit. *)
      DoneWithTurn (* Finished with this turn *)
      END_COMMAND

      COMMAND PUSH ANY
      AtLocation 14 (* In Elevator *)
      NOT VariableEquals 2 0 (* Did player push a number? *)
      PrintMessage 34 (* This Elevator only has four floors. *)
      DoneWithTurn (* Finished with this turn *)
      END_COMMAND


ASKING AND ANSWERING QUESTIONS

Asking and answering questions can be handled by using several
meta-commands.  For example, let's assume we want to ask the trivia
question "What is the largest human organ?" to which the correct answer
is "skin".  We would specify the question and answer in the .DAT file as
follows:

      QUESTION 3 WHAT IS THE LARGEST HUMAN ORGAN?
      ANSWER 3 SKIN

                                                                             87

Then the following meta-commands would ask the question and give an appropriate
response based on whether the answer given was right or wrong:

      COMMAND Verb Noun or ANY
      various conditions
      AskQuestion 3 (* ask it and get answer *)
      TurnFlagON 255 (* temporary flag to test correctness of answer *)
      AnswerIsCorrect (* tests if answer is correct *)
      TurnFlagOFF 255 (* turn temporary flag off because answer right *)
      PrintMessage 29 (* Fantastic, you got it right!! *)
      PlusScore 10 (* Give player 10 points for correct answer *)
      DoneWithTurn
      END_COMMAND

      COMMAND Same Verb Noun or ANY
      FlagON 255 (* temporary flag not turned off in previous COMMAND *)
      TurnFlagOFF 255 (* turn temporary flag off now *)
      PrintMessage 30 (* Sorry, you got it wrong!! *)
      DoneWithTurn
      END_COMMAND

When a question is asked and a response is given, the correct answer is
matched against the response by looking for the answer anywhere in the
response.  This means that any of the following responses would be
considered correct by AGT:

      SKIN
      I THINK THE ANSWER IS SKIN
      THE CORRECT RESPONSE IS "SKIN"
      ANYONE KNOWS IT IS SKIN, YOU TURKEY COMPUTER!

The game designer can have up to 25 sets of questions and answers (1 to
25) in the .DAT file.  They could form the basis for a series of riddles
that must be answered during the course of the adventure in order to get
all the points and win the game.


DEALING WITH MULTIPLE NOUNS WITH THE SAME NAME

Occasionally, the game designer will have to deal with the situation
where there are multiple nouns in the current room with the same name. 
There are several meta-command tokens that have been specifically
developed to help deal with this situation.  The first two are:

      NOUNIsNumber num  -- will test whether the NOUN in the player's
      current input command is NOUN num and return a TRUE condition if
      the noun's number was num and a FALSE condition otherwise.

      ObjectIsNumber num -- will perform a similar test on the OBJECT in
      the player's current input command.

                                                                             88

These two meta-command tokens will be useful whenever the game has a
variety of nouns and objects with the same name and the game designer
only wants to allow certain actions to occur when specific nouns and/or
objects are used in the player's input command.  For example, let's
consider a scenario where there are multiple "drawers" and multiple
"keys" -- potentially all in the same room -- and we want the "brass
key" (NOUN 210) to break whenever it is used to unlock the "middle
drawer" (NOUN 203).  This could be done using these two tokens as
follows:

      COMMAND UNLOCK DRAWER WITH KEY
      Present 210 (* Brass key is here *)
      Present 203 (* Middle drawer is here *)
      NOUNIsNumber 203 (* The middle drawer was specified in input *)
      ObjectIsNumber 210 (* The brass key was also specified in input *)
      SwapLocations 210 211 (* Swap brass key for broken key *)
      PrintMessage 59 (* The key broke in the lock *)
      UnLockIt 203 (* Unlock middle drawer *)
      DoneWithTurn
      END_COMMAND


HANDLING THE CONTENTS OF VARIOUS THINGS

AGT has two meta-command tokens that are extremely useful whenever you
needed to deal with the contents of ROOMs, NOUNs or CREATUREs:

      SomethingInside num -- will test whether entity num has something
      inside it.  Num can be a number for a ROOM, a NOUN or a CREATURE.

      ShowContents num -- will display the contents of the entity num if
      that entity has something inside it.  If there is nothing inside
      the entity num, this token will have no effect.

As an example of how these tokens might be used, let's continue with the
above scenario.  Specifically, let's develop some meta-commands for the
situation where the player wishes to SEARCH THE MIDDLE DRAWER:

      COMMAND SEARCH THE DRAWER
      Present 203 (* Middle drawer is here *)
      NOUNIsNumber 203 (* The middle drawer was specified in input *)
      IsLocked 203 (* The middle drawer is locked *)
      PrintMessage 65 (* The $adjective$ $noun$ is locked. *)
      DoneWithTurn
      END_COMMAND

                                                                             89

      COMMAND SEARCH THE DRAWER
      Present 203 (* Middle drawer is here *)
      NOUNIsNumber 203 (* The middle drawer was specified in input *)
      IsUnLocked 203 (* The middle drawer is unlocked *)
      OpenIt 203 (* Open the middle drawer -- first *)
      NOT SomethingInside 203 (* The middle drawer is empty. *)
      PrintMessage 66 (* The $adjective$ $noun$ is empty. *)
      DoneWithTurn
      END_COMMAND

      COMMAND SEARCH THE DRAWER
      Present 203 (* Middle drawer is here *)
      NOUNIsNumber 203 (* The middle drawer was specified in input *)
      IsUnLocked 203 (* The middle drawer is unlocked *)
      OpenIt 203 (* Open the middle drawer -- first *)
      SomethingInside 203 (* The middle drawer is NOT empty. *)
      PrintMessage 67 (* The $adjective$ $noun$ contains: *)
      ShowContents 203 (* Display contents of middle drawer *)
      DoneWithTurn
      END_COMMAND


OPENING AND CLOSING PASSAGEWAYS BETWEEN ROOMS

The ChangePassageway token can be used in a meta-command to open or
close passageways between rooms during the game.  For example, to open a
secret passage between room 3 and room 7 when the command SESAME is
given could be done with the following:

      COMMAND SESAME
      AtLocation 3 (* Player is at location 3 *)
      InRoom 203 (* Solid stone wall *)
      ChangePassageway 2 7 (* open passage South(2) to room 7 *)
      SwapLocations 203 204 (* Swap solid wall for wall with door in it*)
      SwapLocations 227 228 (* Swap for wall with door in room 7 also *)
      PrintMessage 21 (* At the sound of your voice, a large doorway *)
                      (* magically appears where a stone wall once was. *)
      DoneWithTurn
      END_COMMAND

Once this meta-command has opened the passageway between these rooms,
the player could go to room 7 from room 3 by giving the SOUTH, or
conversely go to room 3 from room 7 by giving the command NORTH.  The
passageway is opened in both rooms in opposite directions.

The same token can be used to close a passageway as well.  For example,
if the statue in the treasure room was "booby-trapped", a command of GET
STATUE might cause an avalanche of rocks to close the west exit from the
treasure room as follows:

                                                                             90

      COMMAND GET STATUE
      AtLocation 23 (* Player is in the Treasure room *)
      InRoom 245 (* statue *)
      FlagOFF 3 (* Booby trap has not been tripped (yet) if OFF *)
      TurnFlagON 3 (* It has now been tripped *)
      ChangePassageway 4 0 (* close(0) passageway to the West(4) *)
      SwapLocations 211 212 (* Swap doorway with jumble of rocks *)
      SwapLocations 213 214 (* Put jumble of rocks in other room also *)
      PrintMessage 25 (* As you pick up the statue, a lever underneath *)
                      (* pops up.  There is a terrible crash and an *)
                      (* avalanche of rocks buries the doorway!! *)
      GetIt 245 (* You wanted it -- You got it!! *)
      DoneWithTurn
      END_COMMAND

The numbers corresponding to the various directions are as follows:

      1 - North     5 - NorthEast      9 - Up
      2 - South     6 - NorthWest     10 - Down
      3 - East      7 - SouthEast     11 - Enter
      4 - West      8 - SouthWest     12 - Exit


META-COMMAND REDIRECTION

Meta-commands can be redirected to other meta-commands.  The principal
use of this capability is when there are several player input commands
which should be handled by the game in the same way.  For example, in
the CAVE adventure, we want the same series of meta-commands to be used
if the player enters "WATER THE PLANT" or "POUR WATER ON THE PLANT". 
With meta-command redirection, the series of meta-commands we wish to
use needs to be given only once in the .CMD file.  The second use can be
simply redirected to the first.  For example, let's assume that all of
the necessary meta-commands are given completely for POUR WATER ON
PLANT, then the appropriate redirection for WATER PLANT could be
accomplished by the following lines in the .CMD file:

      COMMAND WATER PLANT
      ReDirectTo POUR WATER ON PLANT
      END_COMMAND

Notice in the above example that we redirected the meta-command for a
fixed input command (WATER PLANT) to another fixed command (POUR WATER
ON PLANT).  It is also possible to redirect meta-commands for ANY words. 
For example, if we wished to redirect the meta-command WATER ANY we
could do it with the following:

      COMMAND WATER ANY
      ReDirectTo POUR WATER ON $NOUN$
      END_COMMAND

                                                                             91

Notice that by using $NOUN$ in the "redirected" command, we can "map"
the original command's noun (from WATER PLANT or WATER TREE, or WATER
whatever) to the new command's object.  This redirected command causes
the game to convert a command to "WATER THING" to act as if the player
had actually typed in "POUR WATER ON THING".  In addition to $NOUN$, it
is also possible to use $VERB$, $NAME$ and $OBJECT$ whenever we wish to
"map" these words into another use within a redirected command.  You
should not use ANY in the redirected command, i.e., ReDirectTo POUR
WATER ON ANY would make AGT think the player had actually typed in "POUR
WATER ON ANY".


ORGANIZATION OF THE .CMD FILE

Meta-commands like those described above are processed sequentially by
their order of appearance in the .CMD file.  As a result, the COMMANDs
order is very important!  For example, let's consider a series of
meta-commands to define a new verb FILL.  We want to be able to fill a
bottle with water or oil depending upon where we are.  We want to break
a vase, whenever we try to fill the vase.  Finally, we want to print
several default messages, such as "The bottle is already full.", or 
"The $noun$ isn't here, so you can't $verb$ it!",  or "There is nothing
here to put in the $noun$."  or  "You have to be kidding!  You can't
$verb$ a $noun$!!"  This can be done with the following seven
meta-commands for the verb FILL:

           ; COMMENTS
           ;
           ; FLAGS:
           ;   2  Bottle is full if ON, empty if OFF
           ;
           ; NOUNS:
           ;   225 bottle filled with water
           ;   226 empty bottle
           ;   227 bottle filled with oil
           ;   265 broken vase -- pottery shards
           ;   263 Ming vase

      (1)  COMMAND FILL ANY
           NOT NOUNPresent
           PrintMessage 29 ;The $noun$ isn't here, so you can't $verb$ it!
           DoneWithTurn
           END_COMMAND

      (2)  COMMAND FILL BOTTLE
           FlagON 2 ;bottle is already full
           PrintMessage 105 ;The bottle is already full.
           DoneWithTurn
           END_COMMAND

                                                                             92

      (3)  COMMAND FILL BOTTLE
           AtLocation 3 ;inside building
            OR
           AtLocation 4 ;valley by stream
            OR
           AtLocation 38 ;bottom of pit with stream
            OR
           AtLocation 95 ;cavern with waterfall
            OR
           AtLocation 113 ;reservoir
            OR
           AtLocation 141 ;by building
           PrintMessage 107 ;bottle is now full of water
           SwapLocations 226 225 ;swap empty bottle for water-filled
           TurnFlagON 2 ;bottle is now full
           DoneWithTurn
           END_COMMAND

      (4)  COMMAND FILL BOTTLE
           AtLocation 24 ;east pit of two-pit room
           PrintMessage 108 ;bottle is now full of oil
           SwapLocations 226 227 ;swap empty bottle for oil-filled
           TurnFlagON 2 ;bottle is now full
           DoneWithTurn
           END_COMMAND

      (5)  COMMAND FILL BOTTLE
           PrintMessage 106 ;There is nothing here to put in the $noun$.
           DoneWithTurn
           END_COMMAND

      (6)  COMMAND FILL VASE
           Destroy 263 ;Ming vase
           PutInCurrentRoom 265 ;broken vase pottery shards
           PrintMessage 145 ;You clumsy oaf!  You broke the vase.
           DoneWithTurn
           END_COMMAND

      (7)  COMMAND FILL ANY
           PrintMessage 109 ;You must be kidding! You can't $verb$ a $noun$!
           DoneWithTurn
           END_COMMAND

The numbers shown in front of each of the COMMANDs are just for ease of
this discussion.  Numbers like these should NEVER actually be included
in a .CMD file, because they would lead to serious bugs!

If these COMMANDs were in the .CMD file in the order shown, when the
player entered a command to "FILL something", AGT would first try
COMMAND (1) which would test whether the "something" was present.  If it
was not present, COMMAND (1) would print the default message "The

                                                                             93

something isn't here, so you can't fill it!" and the DoneWithTurn would
cause all AGT process to cease for this turn.  Only if the something was
present, would AGT try COMMANDS (2), (3), etc.

COMMAND (2) to (5) will only be tried in the "something" was the BOTTLE. 
COMMAND (2) would be tried first, and it would test if the bottle was
already full and give an appropriate message if it was full.  COMMAND
(3), which would only be tried if the bottle was empty, would test if
the player was located in places where it was possible to get water, and
fills the bottle with water if possible.  COMMAND (4), which would only
be tried if there was no water at the current location, would test if
the player was at location 24, where there is oil, and fill the bottle
with oil, if possible.  COMMAND (5) would only be tired if the player
was not located near a source of water or a source of oil and it would
print a message that "There is nothing here to put in the bottle".

COMMAND (6) only works if the player's input is FILL VASE.  Because AGT
got past COMMAND (1), we know that the vase is present (otherwise
COMMAND (1) would have caused an "error" message to be printed). 
COMMAND (6) causes the broken pottery shards to be switched with the
vase and an appropriate message to be printed.

COMMAND (7) is the "default" condition for the verb FILL.  It is
activated only if the player gave the input "FILL something" and the
"something" is present, but it is not the BOTTLE or the VASE.  For
example, if the player entered FILL THE ROCK, COMMAND (7) would cause
"You must be kidding! You can't fill a rock!" to be printed.

The order of these COMMANDs is very important!  Specifically, COMMAND
(1) must be first and COMMAND (7) must be last in order for AGT to give
the "correct" and logical default responses to the verb FILL.  Further,
COMMAND (2) must precede and COMMAND (5) must follow COMMANDs (3) and
(4) in order for the input "FILL BOTTLE" to work logically.  It is
important to understand why the above sequence is critical.  Study the
sequence again, if necessary.

Besides, the order of COMMANDs for a specific verb (like FILL), it is
also important to arrange the verbs within the .CMD file in a reasonable
manner.  Specifically, all the meta-commands for each verb should be
grouped together in the .CMD file.  For example:

                                                                             94

            ; ANY Commands

      (1)   COMMAND ANY
             .
             .
      (37)  COMMAND ANY

            ; READ Commands

      (38)  COMMAND READ BOOK
             .
             .
      (46)  COMMAND READ ANY

            ; SEARCH Commands

      (47)  COMMAND SEARCH CLOSET
             .
             .
      (54)  COMMAND SEARCH ANY

            ; CLIMB Commands

      (55)  COMMAND CLIMB ROPE
             .
             .
      (69)  COMMAND CLIMB ANY

            ; SQUEEZE Commands

      (70)  COMMAND SQUEEZE LEMON
             .
             .
      (82)  COMMAND SQUEEZE ANY
             .
             .

All the ANY meta-commands are grouped together; all the READ meta-comma-
nds are together, etc.  Not only is this easier to follow and debug, but
it is faster for AGT to process.  This is because, AGT processes these
meta-commands using a variation of a technique called "Indexed
Sequential Access Method" (also called ISAM).  What this means is: AGT
keeps track of the first and last meta-commands for each verb.  For
example, if the verb was CLIMB, AGT would only consider meta-commands
with indices from 55 to 69.  But within this group, AGT considers them
sequentially.

                                                                             95

AGTNUM AND META-COMMANDS

William D. Martinson has written an excellent utility program for IBM
AGT users that can help manage all of the various numbers in the various
AGT game source files -- including numbers that one would normally have
in the .CMD and .MSG files.  For example, using AGTNUM, it is possible
to substitute a descriptive "label" whenever one would normal use a
number, such as:

      FLAG {flashlight lit}
      VARIABLE {energy left}
      .
      .
      .
      COMMAND ANY
      Present {flashlight}
      FlagON {flashlight lit}
      VariableLT {energy left} 20
      PrintMessage {batteries dying}
      END_COMMAND

      MESSAGE {batteries dying}
      Your batteries will last only #VAR{energy left}# more turns.
      END_MESSAGE

In addition, AGTNUM has a number of other capabilities they can make
developing an AGT game easier.  See the separate documentation for
AGTNUM on the disk for details.

                                                                             96

PART 4:  SAMPLE AGT META-COMMAND SCENARIOS


This Part of the manual presents a number of scenarios where meta-
language  commands have been used to create typical game situations. 
These scenarios are presented in detail by showing how ROOMs, NOUNs and
CREATUREs data are used in the .DAT file, how messages are put in the
.MSG file, and finally how the meta-commands are written to accomplish
the desired effects in the .CMD file.  The specific scenarios to be
presented include: (1) defining the actions for the new verb FIND, (2)
random activities by a castle guard, and (3) interacting with other
characters.


SCENARIO 1: "FIND" VERB ACTIONS

One final scenario from the COLOSSAL CAVE adventure.  In this scenario,
we want to define several actions/responses to the player's input using
the custom user-defined verb "FIND".  Pay particular attention to how
the player is offered a hint (for 5 points) if he inputs "FIND CAVE".

In the CAVE.DAT file we would define a custom verb as:

      VERB
      Dummy_Verb1 FIND
      END_VERB

Several messages are needed in the CAVE.MSG file as follows:

      MESSAGE 24
      You are already carrying the $noun$, dummy!
      END_MESSAGE

      MESSAGE 57
      I don't know where the cave is, but hereabouts no stream can run on
      the surface for very long.  I would try the stream.
      END_MESSAGE

      MESSAGE 59
      I can only tell you what you see as you move about and manipulate
      things.
      I cannot tell you where remote things are.
      END_MESSAGE

      MESSAGE 86
      Okay, If you're so smart, do it yourself!
      END_MESSAGE

      MESSAGE 94
      I believe what you want is right here with you.
      END_MESSAGE

                                                                             97

      MESSAGE 116
      The Dwarf's knife vanished as it struck the wall of the cave.
      END_MESSAGE

      MESSAGE 138
      I daresay whatever you want is around here somewhere.
      END_MESSAGE

      MESSAGE 143
      The hint will cost you 5 points.
      END_MESSAGE

      MESSAGE 175
      Do you want the hint?
      END_MESSAGE

The meta-commands for FIND in the CAVE.CMD file would be as follows: (Be
sure and understand the importance of the order of these COMMANDs.)

      ;FLAGS
      ;Flag 3  Cave is closed if ON and player is in a room with many
      ;        sleeping dwarves -- who should not be awakened!
      ;Flag 9  Temporary flag
      ;Flag 10 A Dwarf is in the room if ON
      ;Flag 12 Hint about how to find cave has been offered if ON

      ; FIND meta-commands

      COMMAND FIND KNIFE
      PrintMessage 116 ;The dwarf's knife vanished.
      DoneWithTurn
      END_COMMAND

      COMMAND FIND ANY
      NOUNIsCarrying
      PrintMessage 24 ;You already have it, dummy!
      DoneWithTurn
      END_COMMAND

      COMMAND FIND ANY
      FlagON 3 ;cave is closed
        OR
      NOUNPresent ;NOUN is here already
      PrintMessage 138 ;It must be around here somewhere.
      DoneWithTurn
      END_COMMAND

      COMMAND FIND DWARF
      FlagON 10 ;dwarf in room
      PrintMessage 94 ;It is here with you.
      DoneWithTurn
      END_COMMAND

                                                                             98

      COMMAND FIND CAVE
      FlagOFF 12 ;The Cave hint has not been offered yet.
      TurnFlagON 12 ;Now Cave hint has been offered
      PrintMessage 175 ;Do you want a hint?
      PromptForYes
      TurnFlagON 9 ;hint has been rejected - so far (Turn Temporary Flag
      ON)
      PrintMessage 143 ;The hint will cost you 5 points
      PrintMessage 1 ;Is that OK?
      PromptForYes
      TurnFlagOFF 9 ;Offer of hint has been accepted (Turn Temp Flag OFF)
      PrintMessage 57 ;Follow the stream to find the cave.
      MinusScore 5 ;hint costs 5 points
      DoneWithTurn
      END_COMMAND

      COMMAND FIND CAVE
      FlagON 9 ;Offer of hint was rejected
               ;(Temporary Flag was not turned OFF in last COMMAND)
      TurnFlagOFF 9 ;Turn temporary Flag OFF now
      PrintMessage 86 ;OK, if you're so smart - do it yourself!
      DoneWithTurn
      END_COMMAND

      COMMAND FIND ANY
      PrintMessage 59 ;Sorry, I can't tell you where remote things are.
                      ; Default message for FIND
      DoneWithTurn
      END_COMMAND


SCENARIO 2: RANDOM ACTIVITIES BY GUARD

This is a modification of a scenario from CRUSADE adventure.  In this
scenario we want to create a number of encounters with guards in various
rooms of the Baron's castle.  We will use only one CREATURE (Guard --
301) and move him around from room to room randomly.  The player can
fight the guard, and will be thrown into a dungeon cell if he loses, and
will cause the guard to be replaced with an unconscious guard if he
wins.  The player can wear a disguise by wearing the Baron's armor.  If
the guard encounters the player wearing the armor, the guard will
mistake the player for the Baron and leave the room.  If the player
attempts to talk to the guard without giving the proper password, the
guard will capture the player and throw him into the dungeon.  If the
player angers the guard in Room 11 (a small room -- high up in the sheer
wall of the cavern), the guard will throw the player down to the cavern
floor far below where the player will lose consciousness and later awake
with a broken leg.  The leg will take a random number of turns to heal. 
Before it heals, the player will be unable to move around.

To give as complete a picture as possible, the needed data for this
scenario will be shown from all three necessary CRUSADE.* files: i.e.,

                                                                             99

CRUSADE.DAT, CRUSADE.MSG and CRUSADE.CMD.  In CRUSADE.DAT we would
define the CREATURE, ROOMs and the various NOUNs needed as:

      CREATURE 301
      guard
      Baron's
      You see one of the Baron's guards.  He looks very angry.
      LOCATION 11
      HOSTILE
      MAN
      END_CREATURE

      CREATURE_DESCR 301
      The guard is about 6 foot 8 inches tall, but he appears even bigger
      as he looms over you.  He looks mean and is rather ugly.
      END_CREATURE_DESCR

      ROOM 10
      Large cavern
      EAST 9
      LIGHT 210  (* Blazing torch *)
      END_ROOM

      ROOM_DESCR 10
      You are in a very large cavern with high sheer walls.  A passage
      leads off to the east.
      END_ROOM_DESCR

      NOUN 269
      walls
      cavern
      The cavern walls are quite steep.  You can't see any way to climb
      them.
      LOCATION 10
      UNMOVABLE
      NOUN_SYNONYMS WALL
      PLURAL
      END_NOUN

      NOUN_DESCR 269
      The walls are very steep and quite smooth.  You can't see any hand
      or foot holds.
      END_NOUN_DESCR

      NOUN 219
      opening
      small
      There is an opening in the wall -- high up near the roof of the
      cavern.
      LOCATION 10
      UNMOVABLE
      END_NOUN

                                                                            100

      NOUN_DESCR 219
      You see a dim light shining out of the opening, but it is too high
      and far to see more.  It looks impossible to get up to the opening
      from your location at the bottom of the cavern.
      END_NOUN_DESCR

      ROOM 11
      Small room
      SOUTH 42
      LIGHT 210  (* Blazing torch *)
      END_ROOM

      ROOM_DESCR 11
      You are in a small room carved into the sheer cavern wall.  The
      south part of the room is totally open and looks out on to the
      cavern floor far below.  Be careful not to go south!  There is a
      doorway to the north.
      END_ROOM_DESCR

      NOUN 215
      leg
      broken
      You have a broken leg and are unable to move.
      LOCATION 0
      UNMOVABLE
      END_NOUN

      NOUN_DESCR 215
      Your leg hurts like the dickens!  You are quite discouraged because
      you will need two good legs to rescue the princess and solve this
      adventure!
      END_NOUN_DESCR

      NOUN 230
      armor
      silver
      The Baron's silver suit of armor stands nearby.
      LOCATION 24
      WEIGHT 25
      SIZE 25
      WEARABLE
      POINTS 10
      END_NOUN

      NOUN_DESCR 230
      The armor is quite fancy, but it still looks like it would be
      useful in a fight.  It would cover its occupant from head to foot.
      END_NOUN_DESCR

                                                                            101

      NOUN 259
      guard
      unconscious
      An unconscious guard lies at your feet.
      LOCATION 0
      WEIGHT 200
      END_NOUN

      NOUN_DESCR 259
      The guard's unconscious body lies in a heap at your feet.  You have
      to step over him as you move about the passageway.  He looks like
      he will be out of action for a long time.
      END_NOUN_DESCR

      ROOM 17
      Guard's quarters
      EAST 16
      END_ROOM

      ROOM_DESCR 17
      You are in the guard's quarters.  It looks like a pig sty -- it is
      so messy.  The door is to the east.
      END_ROOM_DESCR

      HELP 17
      Leave quickly.  It is very dangerous to linger here!
      END_HELP

      ROOM 41
      Cell
      (* No obvious exits *)
      END_ROOM

      ROOM_DESCR 41
      You are in a dingy dungeon cell.  There is straw on the floor.  The
      cell is cold and damp.  You are very depressed by just being here.
      END_ROOM_DESCR

In the CRUSADE.MSG file we would define these needed messages:

      MESSAGE 3
      The guard looks at you suspiciously because you neglected to
      identify yourself by using the proper password.  He knows you
      shouldn't be here and decides that he should take you to the Baron
      for questioning.  He rushes toward you.
      END_MESSAGE

                                                                            102

      MESSAGE 8
      What a great idea!  You must have played this game before, but
      unfortunately you can't do that now.  It is still a good idea and
      you may wish to try it some other time.  But now it is impossible
      ....
      END_MESSAGE

      MESSAGE 25
      because the guard simply won't let you $verb$ the $noun$.
      END_MESSAGE

      MESSAGE 33
      An angry-looking guard suddenly enters the room.  He eyes you
      suspiciously and begins to move quickly and carefully toward you. 
      He reaches for his sword, but pauses as if he is waiting for you to
      make the first move.
      END_MESSAGE

      MESSAGE 42
      The guard gets mad at you because he knows you aren't allowed here. 
      He picks you up and throws you over the edge to the cavern floor
      far below.  He stands at the edge looking down at you and
      laughingly cries, "Stay out!  If you know what is good for you. 
      Next time, I will get rough!"   He laughs again and that is the
      last thing you remember as you drift off into unconsciousness.

      When you awake, you find...
      END_MESSAGE

      MESSAGE 43
      with a broken leg.
      END_MESSAGE

      MESSAGE 44
      Your leg has finally healed.  You are now free to resume your
      quest.
      END_MESSAGE

      MESSAGE 45
      The guard looks you over very carefully, but because you are
      wearing the Baron's armor, the guard mistakes you for the Baron. 
      "Sorry to disturb  you, my Lord!", he says as he quickly leaves the
      room.
      END_MESSAGE

      MESSAGE 49
      The guard grabs your throat with his big hands.  He squeezes until
      you can barely breathe.  You struggle and try to pull his hands
      away.
      END_MESSAGE

                                                                            103

      MESSAGE 50
      Finally, you slip into unconsciousness.  When you awake you find
      yourself in a strange and ugly little room.
      END_MESSAGE

      MESSAGE 51
      At last, you pry his fingers off your wind pipe.  Now able to
      breathe, you get enough strength to slam your elbow into his gut. 
      He lets go of you and doubles over.  You kick him in a very
      vulnerable part of his anatomy and he crumples in a pile on the
      floor.
      END_MESSAGE

In the CRUSADE.CMD we would have several COMMANDs.  First, the
meta-commands that cause the random events related to the guard:

      COMMAND ANY
      NOT InRoom 301  (* Guard *)
      NOT InRoom 259  (* Unconscious Guard *)
      Destroy 301 (* Guard disappears from room after player leaves room *)
      Destroy 259 (* Unconscious Guard's body disappears from room *)
      END_COMMAND

      COMMAND ANY
      Chance 5 (* 5 % chance of guard appearing *)
      AtLocationGT 10  (* Baron's castle area *)
      NOT InRoom 301  (* Guard *)
      NOT InRoom 259  (* Unconscious Guard *)
      PutInCurrentRoom 301  (* Put guard in room *)
      PrintMessage 33   (* Guard suddenly appears *)
      BlankLine
      END_COMMAND

      COMMAND ANY
      Chance 50 (* 50 % chance of guard appearing in his own quarters *)
      AtLocation 17  (* Guard's quarters *)
      NOT InRoom 301  (* Guard *)
      NOT InRoom 259  (* Unconscious Guard *)
      PutInCurrentRoom 301  (* Put guard in room *)
      PrintMessage 33   (* Guard suddenly appears *)
      BlankLine
      END_COMMAND

      COMMAND ANY
      InRoom 301 (* guard *)
      IsWearing 230 (* Baron's Armor *)
      PrintMessage 45 (* Guard thinks you are the Baron and leaves *)
      Destroy 301 (* Guard disappears *)
      END_COMMAND

                                                                            104

      COMMAND ANY
      Chance 25
      AtLocation 11 (* room in wall *)
      InRoom 301 (* Guard *)
      GetIt 215 (* give broken leg to player *)
      GoToRoom 10  (* guard throws you into room 10 *)
      PrintMessage 42
      DoneWithTurn (* no further action -- get next input *)
      END_COMMAND

Now the meta-commands dealing with the broken leg:

      COMMAND ANY
      IsCarrying 215 (* Broken leg *)
      VerbIsDirection (* Trying to move *)
      PrintMessage 8 (* Sorry, but you can't *)
      PrintMessage 43 (* with a broken leg *)
      DoneWithTurn (* no further action -- get next input *)
      END_COMMAND

      COMMAND ANY
      Chance 20
      IsCarrying 215 (* Broken leg *)
      PrintMessage 44 (* Leg is healed *)
      BlankLine
      Destroy 215  (* get rid of broken leg *)
      END_COMMAND

Now the meta-commands corresponding to specific input from the player:

      COMMAND GET ANY
      InRoom 301 (* angry guard *)
      PrintMessage 8 (* Sorry, you can't *)
      PrintMessage 25 (* Guard won't allow it *)
      DoneWithTurn (* no further action -- get next input *)
      END_COMMAND

      COMMAND GET ANY
      IsCarrying 215 (* Broken leg *)
      PrintMessage 8 (* Sorry, you can't *)
      PrintMessage 43 (* with broken leg *)
      DoneWithTurn (* no further action -- get next input *)
      END_COMMAND

      COMMAND OPEN ANY
      InRoom 301 (* angry guard *)
      PrintMessage 8 (* Sorry, you can't *)
      PrintMessage 25 (* Guard won't allow it *)
      DoneWithTurn (* no further action -- get next input *)
      END_COMMAND

                                                                            105

      COMMAND ATTACK GUARD
      InRoom 301 (* angry guard *)
      PrintMessage 49 (* It was a fierce fight *)
      TurnFlagON 255 (* Set Temporary Flag to ON *)
      Chance 25 (* 25 % chance of winning fight *)
      PrintMessage 51 (* but you won! *)
      TurnFlagOFF 255 (* Turn Temporary Flag OFF now *)
      SwapLocations 259 301 (* put unconscious guard in room *)
      DoneWithTurn (* no further action -- get next input *)
      END_COMMAND

      COMMAND ATTACK GUARD
      InRoom 301 (* angry guard *)
      FlagON 255 (* Temporary Flag was not turned OFF in last COMMAND *)
      TurnFlagOFF 255 (* Turn Temporary Flag OFF now *)
      PrintMessage 50 (* but you lost! *)
      SendAllToRoom 17 (* Guard's takes stuff to his quarters *)
      GoToRoom 41 (* Guard puts you in dungeon cell *)
      SendToRoom 202 41 (* Put torch in dungeon with you *)
      DoneWithTurn (* no further action -- get next input *)
      END_COMMAND

      COMMAND TALK TO GUARD
      PrintMessage 3 (* chat with guard -- without using password *)
      PrintMessage 49 (* It was a fierce fight *)
      PrintMessage 50 (* but you lost! *)
      SendAllToRoom 17 (* Guard's takes stuff to his quarters *)
      GoToRoom 41 (* Guard puts you in dungeon cell *)
      SendToRoom 202 41 (* Put torch in dungeon with you *)
      DoneWithTurn (* no further action -- get next input *)
      END_COMMAND

      COMMAND ASK GUARD ABOUT ANY
      ReDirectTo TALK TO GUARD
      END_COMMAND


SCENARIO 3: INTERACTION WITH OTHER CHARACTERS

Let's develop an example of communicating with other characters in an
adventure game.  Specifically, let's consider a situation in a Star Trek
adventure game were we wish to be able to experience the following
interchange between several of the standard Star Trek characters and the
player, who is playing the role of Captain James T. Kirk:

                                                                            106

      You are on the Bridge, the circular room at the top of the Enterprise's
      disk.  The walls are decked with crew members seated or standing at their
      posts. In the center of the room is your command chair.  Along one side
      of the room is a large viewscreen.  The only exit, via turbolift, is aft.
        The viewscreen shows the emptiness and vastness of space.
        Spock stands alert but relaxed, with his arms folded behind his back.
        Chekov sits behind the weapons control console.
        Lieutenant Uhura listens intently to her earphones.
        At the navigator's station, Sulu sits behind a console of controls.

      What now? AFT

      You are in the TurboLift, a small closet-like room.  The Bridge is to your
      west.
        Spock stands alert but relaxed, with his arms folded behind his back.

      What now? WARP 10

      Spock: Jim, surely you realize that you are not on the Enterprise's
      Bridge.  The command "warp 10" is quite inappropriate here.

      What now? WEST

      You are on the Bridge, the circular room at the top of the Enterprise's
      disk.  The walls are decked with crew members seated or standing at their
      posts. In the center of the room is your command chair.  Along one side
      of the room is a large viewscreen.  The only exit, via turbolift, is aft.
        The viewscreen shows the emptiness and vastness of space.
        Spock stands alert but relaxed, with his arms folded behind his back.
        Chekov sits behind the weapons control console.
        Lieutenant Uhura listens intently to her earphones.
        At the navigator's station, Sulu sits behind a console of controls.

      What now? SCOTTY, WARP 10

      Spock: Captain, should you have Doctor McCoy check your eye sight?  
      Surely, you can see that Scotty isn't here.

      What now? CHEKOV, WARP 10

      Spock: Your extensive command experience should have convinced you that
      better results can be obtained when the appropriate member of the crew
      performs this operation.  Permit me to redirection your command to the
      proper crew member.

      Spock: Sulu, warp 10

      Sulu: What course should I plot first, Captain?

      What now? PLOT A COURSE FOR QWERTY

                                                                            107

      Sulu: Plotting a course for the planet Qwerty, Captain.

      What now? WARP 16

      Spock: Captain, surely you realize that the Enterprise is only capable of
      Warp 1 through Warp 12, plus Impulse power, of course.

      What now? WARP 10

      Sulu: Going to warp factor 10.

To see how this scene is achieved, first let's examine the relevant
entries in the .DAT file.  There are only two Rooms in the scene, the
Bridge and the TurboLift; their descriptions are as follows:

      ROOM 114
      Bridge
      EAST 2
      ENTER 2
      EXIT 2
      END_ROOM

      ROOM_DESCR 114
      You are on the Bridge, the circular room at the top of the
      Enterprise's disk.  The walls are decked with crew members seated
      or standing at their posts. In the center of the room is your
      command chair.  Along one side of the room is a large viewscreen. 
      The only exit, via turbolift, is aft.
      END_ROOM_DESCR

      ROOM 2
      Turbolift: Deck 1
      WEST 114 (* Bridge *)
      ENTER 114 (* Bridge *)
      EXIT 114 (* Bridge *)
      END_ROOM

      ROOM_DESCR 2
      You are in the TurboLift, a small closet-like room.  The Bridge is
      to your west.
      END_ROOM_DESCR

Next, let's see how the Nouns are described in the .DAT file:
      
      NOUN 201
      course
      ship's
      You see the course plotted on the navigator's console.
      LOCATION 0
      NOUN_SYNONYMS CONSOLE
      END_NOUN

                                                                            108

      NOUN_DESCR 201
      The navigator's console shows the ship's course plotted in light
      blue.  The Enterprise (shown as a red circle) is on course.
      END_NOUN_DESCR
      
      NOUN 243
      Viewscreen
      Big
      The viewscreen shows the emptiness and vastness of space.
      LOCATION 114 (* Bridge *)
      UNMOVABLE
      NOUN_SYNONYMS SCREEN
      END_NOUN

      NOUN 246
      Qwerty
      Planet
      You notice on the viewscreen:  The planet Qwerty below.
      LOCATION 0
      UNMOVABLE
      NOUN_SYNONYMS PLANET
      END_NOUN

Notice that only the Viewscreen, Noun 243, is in the Bridge, Room 114,
at the beginning of the scene.  The other Nouns are initially "nowhere",
Room 0, and will be put in Room 114, the Bridge, when appropriate. 
Specifically, The Ship's Course, Noun 201, will be put in Room 114 as
soon as a command is given to plot a course.  Similarly, Noun 246, the
planet Qwerty -- shown in the Viewscreen, will replace the empty
Viewscreen when the Enterprise gets close to the planet and assumes
orbit.

There are a number of Creatures in the scene.  Their descriptions would
be given in the .DAT file as follows:

      CREATURE 300
      Spock
      Commander
      Spock stands alert but relaxed, with his arms folded behind his
      back.
      LOCATION 114 (* Bridge *)
      GROUPMEMBER (* Have Spock automatically follow player *)
      END_CREATURE

      CREATURE_DESCR 300
      Spock is the only Vulcan member of your crew.  He wears a blue
      shirt with a gold Star Fleet insignia.
      END_CREATURE_DESCR

                                                                            109

      CREATURE 301
      Chekov
      Lieutenant
      Chekov sits behind the weapons control console.
      LOCATION 114 (* Bridge *)
      END_CREATURE

      CREATURE_DESCR 301
      Chekov is sitting at his assigned station pressing keys on the
      weapons control Panel and monitoring the screen in front of him.
      END_CREATURE_DESCR
      
      CREATURE 302
      Uhura
      Lieutenant
      Lieutenant Uhura listens intently to her earphones.
      LOCATION 114 (* Bridge *)
      UNMOVABLE
      END_CREATURE

      CREATURE_DESCR 302
      Uhura is sitting in her communications station listening to her
      earphones and monitoring all of the known hailing frequencies.
      END_CREATURE_DESCR

      CREATURE 303
      Sulu
      Commander
      At the navigator's station, Sulu sits behind a console of controls.
      LOCATION 114 (* Bridge *)
      UNMOVABLE
      END_CREATURE

      CREATURE_DESCR 303
      Sulu is sitting next to Chekov, monitoring the lit navigation
      console.
      END_CREATURE_DESCR

      CREATURE 305
      Scott
      Commander
      Commander Scott sits at his console, monitoring the ship's engines.
      LOCATION 52 (* Engine Room *)
      UNMOVABLE
      CREATURE_SYNONYMS SCOTTY
      END_CREATURE

      CREATURE_DESCR 305
      Scott is the best Engineering Officer in the Federation.
      END_CREATURE_DESCR

                                                                            110

All of these Creatures are initially in the Bridge, Room 114, except for
Commander Scott, who is in the Engine Room, naturally.

Only one other entry from the .DAT file needs to be specified in order
for the scene to work as show, and that is the definition of verbs:

      VERB
      EAST AFT
      Dummy_Verb1 WARP
      Dummy_Verb2 PLOT SET CHART
      END_VERB

Notice that AFT is defined as a synonym for EAST.  WARP is defined as a
"custom" verb so that commands like WARP 9 will be understood by the
parser and the rest of the AGT driver program (RUN.EXE).  Integer
numbers like 9, 12, etc., are always acceptable "Nouns" to the parser;
however, you must use meta-commands to deal with numbers as Nouns
properly.  PLOT, SET and CHART are all synonyms so that the player can
enter PLOT A COURSE, or SET A COURSE or CHART A COURSE and they will all
be treated the same by AGT.

The messages needed for the scene are contained in the .MSG file and are
shown below:

      MESSAGE 105
      Spock: Captain, should you have Doctor McCoy check your eye sight? 
      Surely, you can see that $Name$ isn't here.
      END_MESSAGE

      MESSAGE 106
      Spock: Your extensive command experience should have convinced you
      that better results can be obtained when the appropriate member of
      the crew performs this operation.  Permit me to redirection your
      command to the proper crew member.
      END_MESSAGE

      MESSAGE 107
      Spock: Sulu, $verb$ $noun$.
      END_MESSAGE

      MESSAGE 108
      Spock: Jim, surely you realize that you are not on the Enterprise's
      Bridge.  The command "$VERB$ $NOUN$" is quite inappropriate here.
      END_MESSAGE

      MESSAGE 109
      Spock: Captain, surely you realize that the Enterprise is only
      capable of Warp 1 through Warp 12, plus Impulse power, of course.
      END_MESSAGE

                                                                            111

      MESSAGE 110
      Sulu: What course should I plot first, Captain?
      END_MESSAGE

      MESSAGE 111
      Sulu: Going to warp factor $noun$.
      END_MESSAGE

      MESSAGE 112
      Sulu: Plotting a course for the planet $Object$, Captain.
      END_MESSAGE

Now for the heart of the scene's interaction, the .CMD file meta-
commands.  First, any input command that the player addresses to a valid
Creature in the game will first be tried against a group of meta-
commands that are addressed to ANYBODY.  This will happen automatically. 
For example, consider the following ANYBODY meta-commands:

      COMMAND ANYBODY, ANY
      NOT NamePresent (* Addressee isn't here. *)
      PrintMessage 105 (* Sorry, but $Name$ doesn't seem to be here. *)
      DoneWithTurn
      END_COMMAND

      COMMAND ANYBODY, WARP ANY
      AtLocation 114 (* On Enterprise's Bridge *)
      NOT NameIsNumber 303 (* Command isn't being addressed to Sulu *)
      PrintMessage 106 (* Spock: You should address appropriate person. *)
      PrintMessage 107 (* Spock redirects command to Sulu for you. *)
      RedirectTo WARP $NOUN$
      END_COMMAND

      COMMAND ANYBODY, WARP ANY
      RedirectTo WARP $NOUN$
      END_COMMAND

The first of the above will be tried for any player command that has
been addressed to a Creature, no matter what the command is.  For
example, this command will be tried if the player enters SPOCK, FOLLOW
ME or SULU, WARP 12.  However, it would not be tried if the player did
not direct his command to anyone, i.e., it would not be tried if the
player simply inputs WARP 12 without addressing it to a specific
creature.  This first meta-command simply tests that the Creature being
addressed in the command is at the current location and prints a "error"
message if the creature isn't there.

The second and third meta-commands above are tried whenever a player
addresses his command to a Creature (any Creature, however) and the
command is to WARP something.  The second meta-command checks if the
creature being addressed is Sulu, and if it isn't -- gives an "error"
message and redirects the command to Sulu.  The third meta-command would

                                                                            112

only be tried if the player input SULU, WARP Something.  This meta-
command simply redirects the command to WARP Something, as if the
command had not been addressed to anyone specifically.

These WARP Something meta-commands would be defined in the .CMD file as
follows:

      COMMAND WARP ANY
      NOT AtLocation 114 (* NOT On Enterprise's Bridge *)
      PrintMessage 108 (* Spock: "$VERB$ $NOUN$" is inappropriate here. *)
      DoneWithTurn
      END_COMMAND

      COMMAND WARP ANY
      NounToVariable 1 (* Convert Noun to Variable number 1 *)
      VariableGT 1 12
      OR
      VariableLT 1 1
      PrintMessage 109 (* The Enterprise can only travel at warp 1 to 12. *)
      DoneWithTurn
      END_COMMAND

      COMMAND WARP ANY
      FlagOFF 1 (* Course has not been plotted yet *)
      PrintMessage 110 (* Sulu: What course to plot first, Captain? *)
      DoneWithTurn
      END_COMMAND

      COMMAND WARP ANY
      FlagON 1 (* Course has been plotted already *)
      PrintMessage 111 (* Sulu: Going to warp factor $noun$. *)
      DoneWithTurn
      END_COMMAND

The first three of the above meta-commands check for various "error"
conditions and give "error" messages if appropriate.  Specifically, the
first meta-command tests if the player is not on the Bridge; the second
tests if the warp speed is outside the acceptable range; and the third
tests that a course has already been plotted.  Only if none of these
"error" conditions are met, would the fourth meta-command tell that
player that the Enterprise was going to the indicated warp speed.

There are only two more meta-commands required in order for the scene to
work as shown at the start of this section.  These meta-commands are
both for the situation where the player enters a command to PLOT A
COURSE TO Somewhere:

                                                                            113

      COMMAND PLOT COURSE FOR ANY
      NOT AtLocation 114 (* NOT On Enterprise's Bridge *)
      PrintMessage 108 (* Spock: "$VERB$ $NOUN$" is inappropriate here. *)
      DoneWithTurn
      END_COMMAND

      COMMAND PLOT COURSE FOR ANY
      TurnFlagON 1 (* Course has now been plotted *)
      DropIt 201 (* Put plotted course on Navigator's console *)
      PrintMessage 112 (* Sulu: Plotting course for $Object$. *)
      DoneWithTurn
      END_COMMAND


                                                                            114

PART 5:  "DEBUGGING" YOUR ADVENTURE

Once the "first draft" of your adventure is completed, you will want to
begin a process known as "play testing" or "debugging."  This process is
where you (and perhaps a few friends) test your game to see that it
behaves the way you intended -- not the way you actually programmed it.

This process is both very rewarding and very frustrating.  You can be
guaranteed that you will discover "bugs" in your game.  You can also be
guaranteed that while debugging your game, you will come up with a whole
host of improvements -- your descriptions will become brighter, your
puzzles will become cleverer, and you will think of entirely new and
absolutely brilliant game scenes to "spice" up the game.

AGT's RUN program has some built-in "magic" words that can make
debugging much easier.  For example, you can give the command MOVEPLAYER
(note: there is no space between MOVE and PLAYER) and you will be
"transported" instantly to another room.  A complete list of the
debugging "magic" words follows:

      DEBUGCOMMANDS -- will turn on (or off) the meta-commands "debug"
      option, i.e., it will toggle FLAG 0.

      GETNOUN -- will enable you to immediately get a particular noun --
      no matter where it is located.

      MOVENOUN -- will enable you to move a noun from its current
      location to any other location in the game.

      MOVECREATURE -- will enable you to relocate a creature from its
      current location to any other location in the game.

      MOVEPLAYER -- will enable you to be "transported" instantly to
      another room.

      LISTROOMS -- will give you a complete list of the numbers and short
      descriptions for all of the rooms in the game.  This is
      particularly helpful, when you know you want to be in the "Dank
      Dungeon", but you can't remember its room number.

      LISTNOUNS -- will give you a complete list of the numbers, names
      and current locations for all of the nouns in the game.  This is
      particularly helpful, when you know you want to find the "Iron
      Maiden", but you can't remember where you left it.

      LISTCREATURES -- will give you a complete list of the numbers,
      names and current locations for all of the creatures in the game. 
      This is particularly helpful, when you know you want to see if the
      magic word "QWERTY" really does make the Ogre run away and hide,
      but you can't remember where the Ogre is to begin with.

Remember, you can use the SCRIPT command to get a hard-copy of any of these
lists.

                                                                            115

APPENDIX A:  AGT STANDARD LEVEL VERBS


Meanings of notation:
  [required word]
  {optional word}
  | (means OR, i.e., alternative words)

Verbs that do not require nouns
===============================
 N,S,E,W,NE,NW,SE,SW,U,D,
 NORTH,SOUTH,EAST,WEST,NORTHEAST,NORTHWEST,SOUTHEAST, SOUTHWEST,UP,DOWN
 ENTER | GO [IN | INTO]
 EXIT | LEAVE  (* directions *)

 SCORE  (* display score and status *)
 QUIT | Q  (* end game *)
 INVENTORY | I  (* list things player is carrying and wearing *)
 SCREAM | SHOUT | YELL  (* make noise but seldom accomplish anything *)
 WAIT  (* waste a turn *)
 BRIEF | VERBOSE  (* change description mode *)
 L | LOOK  (* repeat full description *)
 SAVE | RESTORE {GAME}  (* save and restore game status *)
 HELP | H  (* ask for help *)
 AGAIN | G (* repeat last command entered *)
 SCRIPT  (* echo all output to both printer (LP1:) and screen *)
 UNSCRIPT  (* send all output to screen only *)

Verbs that do require nouns (and perhaps objects)
=================================================
 LIST | SHOW [EXITS]  (* list visible exits *)
 THROW | CAST | DUMP [noun]
    {[AT | TO | IN | INTO | ACROSS | INSIDE] [noun]}
 ATTACK | KILL | FIGHT | HIT [creature] {[WITH] [noun]}
 DROP | PUT DOWN [noun | ALL]
 GET | TAKE | PICK UP [noun | ALL]
 OPEN [noun] {[WITH] [noun]}
 CLOSE | SHUT [noun]
 LOCK [noun] {[WITH] [noun]}
 UNLOCK [noun] {[WITH] [noun]}
 EXAMINE | CHECK | INSPECT | LOOK AT | LOOK IN [noun]
 READ [noun]
 EAT [noun]
 DRINK [noun]
 PUT | PLACE [noun]
    [IN | WITH | INSIDE | INTO | NEAR | BEHIND | BESIDE |
     ON | UNDER] [noun]
 PUSH | TOUCH [noun] {[WITH] [noun]}
 TURN [noun] {ON | OFF}
 TURN {ON | OFF} [noun]
 PULL [noun]
 PLAY {WITH} [noun]

                                                                            116

 LIGHT [noun]
 EXTINGUISH | PUT OUT [noun]  (* synonym is "EXT" *)
 SHOOT | FIRE [noun] [AT] [creature]
 SHOOT | FIRE [creature] [WITH] [noun]
 PUT ON | WEAR [noun | ALL]
 TAKE OFF | REMOVE [noun | ALL]
 ASK [creature] [ABOUT] [noun]
 TALK [TO | WITH] [creature] {[ABOUT] [noun]}
 TELL [creature] [ABOUT] [noun]

                                                                            117

APPENDIX B:  META-COMMANDS CONDITIONAL TESTS



                          ____________________
 ________________________|  PLAYER CONDITIONS |_______________________________
|                        |____________________|                               |
|                      NUMBER/TYPES                                           |
| TOKEN NAME           OF PARAMETERS              EXPLANATION                 |
|_____________________________________________________________________________|
| AtLocation          |1|Location#  | Player is located at room Location#     |
| AtLocationGT        |1|Location#  | Player is in room greater than Location#|
| AtLocationLT        |1|Location#  | Player is in room less than Location#   |
| FirstVisitToRoom    |0|None       | First visit to current room             |
| IsCarryingSomething |0|None       | Player is carrying something            |
| IsCarryingNothing   |0|None       | Player is carrying nothing              |
| IsCarryingTreasure  |1|Points#    | Player is carrying at least one item    |
|                     | |           |    that is worth at least Points#       |
| IsWearingSomething  |0|None       | Player is wearing something             |
| IsWearingNothing    |0|None       | Player is wearing nothing               |
| LoadWeightEquals    |1|Number     | Player's load weighs equals Number      |
| LoadWeightGT        |1|Number     | Player's load weighs more than Number   |
| LoadWeightLT        |1|Number     | Player's load weighs less than Number   |
| NewLife             |0|None       | Player has just been resurrected or     |
|                     | |           |    start of game                        |
|_____________________|_|___________|_________________________________________|

                                                                            118



                          ____________________
 ________________________| ITEM(S) CONDITIONS |_______________________________
|                        |____________________|                               |
|                      NUMBER/TYPES                                           |
| TOKEN NAME           OF PARAMETERS              EXPLANATION                 |
|_____________________________________________________________________________|
| Present             |1|Item#      | Item# is in room, carried or worn       |
| IsWearing           |1|Item#      | Item# is being worn                     |
| IsCarrying          |1|Item#      | Item# is being carried                  |
| IsNowhere           |1|Item#      | Item# is located NOWHERE (in room 0)    |
| IsSomewhere         |1|Item#      | Item# is located somewhere (not in 0)   |
| InRoom              |1|Item#      | Item# is located in current room        |
| IsLocated           |2|Item# Loc# | Item# is located in room Location#      |
| Together            |2|Itm1# Itm2#| Itm1# and Itm2# are in same place       |
| IsON                |1|Item#      | Item# is ON                             |
| IsOFF               |1|Item#      | Item# is OFF                            |
| IsOpen              |1|Item#      | Item# is Open                           |
| IsClosed            |1|Item#      | Item# is Closed                         |
| IsLocked            |1|Item#      | Item# is Locked                         |
| IsUnLocked          |1|Item#      | Item# is UnLocked                       |
| IsEdible            |1|Item#      | Item# is Edible                         |
| IsDrinkable         |1|Item#      | Item# is Drinkable                      |
| IsPoisonous         |1|Item#      | Item# is Poisonous                      |
| IsMovable           |1|Item#      | Item# is Movable                        |
| IsGroupMember       |1|Item#      | Item# is a member of the group          |
| SomethingInside     |1|Item#      | Item# has something inside it.  Item#   |
|                     | |           |   can represent a ROOM, NOUN or CREATURE|
|_____________________|_|___________|_________________________________________|

                                                                            119


                                                                              
                          ____________________
 ________________________|   NOUN CONDITIONS  |_______________________________
|                        |____________________|                               |
|                      NUMBER/TYPES                                           |
| TOKEN NAME           OF PARAMETERS              EXPLANATION                 |
|_____________________________________________________________________________|
| NOUNPresent         |0|None       | NOUN is in room, carried or worn        |
| NOUNIsWearing       |0|None       | NOUN is being worn                      |
| NOUNIsCarrying      |0|None       | NOUN is being carried                   |
| NOUNIsNowhere       |0|None       | NOUN is located NOWHERE (in room 0)     |
| NOUNIsSomewhere     |0|None       | NOUN is located somewhere (not room 0)  |
| NOUNInRoom          |0|None       | NOUN is located in current room         |
| NOUNIsLocated       |1|Location#  | NOUN is located in room Location#       |
| NOUNIsON            |0|None       | NOUN is ON                              |
| NOUNIsOFF           |0|None       | NOUN is OFF                             |
| NOUNIsOpen          |0|None       | NOUN is Open                            |
| NOUNIsClosed        |0|None       | NOUN is Closed                          |
| NOUNIsLocked        |0|None       | NOUN is Locked                          |
| NOUNIsUnLocked      |0|None       | NOUN is UnLocked                        |
| NOUNIsEdible        |0|None       | NOUN is Edible                          |
| NOUNIsDrinkable     |0|None       | NOUN is Drinkable                       |
| NOUNIsPoisonous     |0|None       | NOUN is Poisonous                       |
| NOUNIsMovable       |0|None       | NOUN is Movable                         |
| NOUNpointsEquals    |1|Number     | NOUN's points equal Number              |
| NOUNpointsGT        |1|Number     | NOUN's points are greater than Number   |
| NOUNpointsLT        |1|Number     | NOUN's points are less than Number      |
| NOUNweightEquals    |1|Number     | NOUN's weight equals Number             |
| NOUNweightGT        |1|Number     | NOUN's weight is greater than Number    |
| NOUNweightLT        |1|Number     | NOUN's weight is less than Number       |
| NOUNIsCreature      |0|None       | NOUN is a creature, rather than Noun    |
| NOUNIsNumber        |1|Number     | NOUN's num is Number, e.g., NOUN is     |
|                     | |           |    number 235                           |
|_____________________|_|___________|_________________________________________|

                                                                            120



                      ____________________________
 ____________________|  MISCELLANEOUS CONDITIONS  |___________________________
|                    |____________________________|                           |
|                      NUMBER/TYPES                                           |
| TOKEN NAME           OF PARAMETERS              EXPLANATION                 |
|_____________________________________________________________________________|
| NamePresent         |0|None       | Addressee is present in current room    |
| NameIsNumber        |1|Number     | Addressee is Creature or Noun number    |
| ObjectPresent       |0|None       | Object is present                       |
| ObjectIsCreature    |0|None       | Object is a Creature                    |
| ObjectIsNumber      |1|Number     | Object is Creature or Noun number       |
| LightPresent        |0|None       | Current room has necessary light        |
| RoomNeedsLight      |0|None       | Current room needs a light              |
| FlagON              |1|Flag#      | Flag# is ON                             |
| FlagOFF             |1|Flag#      | Flag# is OFF                            |
| ScoreEquals         |1|Number     | Current score is equal to Number        |
| ScoreGT             |1|Number     | Score is greater than Number            |
| ScoreLT             |1|Number     | Score is less than Number               |
| NumberEquals        |1|Number     | Number input is equal to Number         |
| NumberGT            |1|Number     | Number is greater than Number           |
| NumberLT            |1|Number     | Number is less than Number              |
| AnswerIsCorrect     |0|None       | Last answer was correct                 |
| AnswerIsWrong       |0|None       | Last answer was wrong                   |
| TurnsEquals         |1|Number     | Number of turns is equal to Number      |
| TurnsGT             |1|Number     | Number of turns is greater than Number  |
| TurnsLT             |1|Number     | Number of turns is less than Number     |
| CounterEquals       |2|Ctr# Number| Counter# is equal to Number             |
| CounterGT           |2|Ctr# Number| Counter# is greater than Number         |
| CounterLT           |2|Ctr# Number| Counter# is less than Number            |
| VariableEquals      |2|Var# Number| Variable# is equal to Number            |
| VariableGT          |2|Var# Number| Variable# is greater than Number        |
| VariableLT          |2|Var# Number| Variable# is less than Number           |
| CompareVariables    |2|Var#1 Var#2| Variable#1 is less than Variable#2      |
| VariableChance      |2|Var# Number| Variable# is less than a random number  |
|                     | |           |    from 1 to Number                     |
| Chance              |1|Percent    | Odds percent, i.e., 10 % chance of TRUE |
| PromptForYES        |0|None       | Prompts for Y or N -- TRUE if Yes       |
| PromptForNO         |0|None       | Prompts for Y or N -- TRUE if No        |
| VerbIsDirection     |0|None       | Verb is movement or direction           |
|_____________________|_|___________|_________________________________________|

                                                                            121

APPENDIX C:  META-COMMANDS ACTION TOKENS



                         ________________________
 _______________________|  PLAYER ACTION TOKENS  |____________________________
|                       |________________________|                            |
|                      NUMBER/TYPES                                           |
| TOKEN NAME           OF PARAMETERS              EXPLANATION                 |
|_____________________________________________________________________________|
| GoToRoom            |1|Location#  | Send player to Location#                |
| GoToRandomRoom      |2|Loc#1 Loc#2| Randomly pick a room between Loc#1 and  |
|                     | |           |    Loc#2 and send player to it          |
| GetIt               |1|Item#      | Item# is now being carried              |
| WearIt              |1|Item#      | Item# is now being worn                 |
| DropIt              |1|Item#      | Drop Item# into current room            |
| RemoveIt            |1|Item#      | Remove Item# and drop into room         |
| GetNOUN             |0|None       | NOUN is now being carried               |
| WearNOUN            |0|None       | NOUN is now being worn                  |
| DropNOUN            |0|None       | Drop NOUN into current room             |
| RemoveNOUN          |0|None       | Remove NOUN and drop into room          |
| DropEverything      |0|None       | Drop all items being carried            |
| RemoveEverything    |0|None       | Remove all items being worn             |
| KillPlayer          |0|None       | Make player dead at end of turn         |
|_____________________|_|___________|_________________________________________|


                                                                            122


                     ____________________________________
 ___________________|  ITEM/NOUN/LOCATION ACTION TOKENS  |____________________
|                   |____________________________________|                    |
|                      NUMBER/TYPES                                           |
| TOKEN NAME           OF PARAMETERS              EXPLANATION                 |
|_____________________________________________________________________________|
| PutInCurrentRoom    |1|Item#      | Put Item# in current room               |
| PutNOUNInCurrentRoom|0|None       | Put NOUN in current room                |
| RelocateAll         |2|Loc1# Loc2#| Relocate all items at Loc1# to Loc2#    |
| SendToRoom          |2|Item# Loc# | Put Item# in room Location#             |
| SendNOUNToRoom      |1|Location#  | Put NOUN in room Location#              |
| SendAllToRoom       |1|Location#  | Send all carried items to Location#     |
| SendTreasuresToRoom |2|Loc# Point#| Send all carried items whose            |
|                     | |           |    points > Point# to Loc#              |
| Destroy             |1|Item#      | Item# is now NOWHERE (in room 0)        |
| DestroyNOUN         |0|None       | NOUN is now NOWHERE (in room 0)         |
| SwapLocations       |2|Itm#1 Itm#2| Swap locations of Item#1 & Item#2       |
| SendToItem          |2|Itm#1 Itm#2| Put Itm#1 in location of Itm#2          |
| SendNOUNToItem      |1|Item#      | Put NOUN in location of Item#           |
| OpenIt              |1|Item#      | Item# is now open                       |
| CloseIt             |1|Item#      | Item# is now closed                     |
| LockIt              |1|Item#      | Item# is now locked                     |
| UnlockIt            |1|Item#      | Item# is now unlocked                   |
| OpenNOUN            |0|None       | NOUN is now open                        |
| CloseNOUN           |0|None       | NOUN is now closed                      |
| LockNOUN            |0|None       | NOUN is now locked                      |
| UnlockNOUN          |0|None       | NOUN is now unlocked                    |
| AddToGroup          |1|Item#      | Adds Item# to group                     |
| RemoveFromGroup     |1|Item#      | Removes Item# from group                |
| MoveTheGroup        |1|Location#  | Move group to Location#                 |
|_____________________|_|___________|_________________________________________|

                                                                            123


                     _________________________________
 ___________________|   MISCELLANEOUS ACTION TOKENS   |_______________________
|                   |_________________________________|                       |
|                      NUMBER/TYPES                                           |
| TOKEN NAME           OF PARAMETERS              EXPLANATION                 |
|_____________________________________________________________________________|
| ShowScore           |0|None       | Show current SCORE                      |
| PlusScore           |1|Number     | Add Number to current SCORE             |
| MinusScore          |1|Number     | Subtract Number from current SCORE      |
| ShowInventory       |0|None       | Show current INVENTORY                  |
| ShowContents        |1|Number     | Show contents (if any) of entity Number |
| WaitForReturn       |0|None       | Print 'Hit RETURN' message and wait     |
| TimePasses          |0|None       | Show 'Time passes...' message           |
| Delay               |1|Number     | Delay for Number seconds                |
| ClearScreen         |0|None       | Clear screen                            |
| DescribeThing       |1|Number     | Describe thing Number (whatever)        |
| LookAtRoom          |0|None       | Cause a VERBOSE look at room            |
| Tone                |2|Hz Ms      | Makes a tone on speaker of Hz Hertz (440|
|                     | |           |  Hertz = A on piano) for Ms milliseconds|
| PrintMessage        |1|Number     | Print message Number in .MSG file       |
| RandomMessage       |2|Num1 Num2  | Randomly picks a message from Num1 to   |
|                     | |           |   Num2 in .MSG file and prints it       |
| BlankLine           |0|None       | Print a blank line                      |
| GetNumberInput      |2|Num1 Num2  | Prompt for player to input a Number     |
|                     | |           |   where Num1 <= Number <= Num2.         |
|                     | |           |   If Num1=Num2, then no range will be   |
|                     | |           |   given in prompt.                      |
| AskQuestion         |1|Question#  | Ask and get answer to question#         |
| ChangePassageway    |2|Dir# Loc#  | Create or close a passageway            |
|                     | |           |   from current_room to Loc# via Dir#.   |
|                     | |           |   Dir# = 1 = north...Dir # = 12 = exit. |
|                     | |           |   If Loc# = 0 then closes passageway.   |
|                     | |           |   If Loc# <> 0 then opens passageway    |
|                     | |           |   to room Loc# via direction Dir#.      |
|                     | |           |   Passageways are opened or closed at   |
|                     | |           |   both ends simultaneously!             |
| TurnFlagON          |1|Flag#      | Turn Flag# ON                           |
| TurnFlagOFF         |1|Flag#      | Turn Flag# OFF                          |
| ToggleFlag          |1|Flag#      | Toggle Flag#                            |
| TurnCounterON       |1|Counter#   | Turn Counter# ON -- sets to 1           |
| TurnCounterOFF      |1|Counter#   | Turn Counter# OFF -- sets to 0          |
| SetVariableTo       |2|Var# Number| Set Variable Var# to Number             |
| AddToVariable       |2|Var# Number| Add Number to Var#                      |
| SubtractFromVariable|2|Var# Number| Subtract Number from Var#               |
| AddVariables        |2|Var#1 Var#2| Add Var#2 and Var#1 and put answer      |
|                     | |           |   into Var#1                            |
| SubtractVariables   |2|Var#1 Var#2| Subtract Var#2 from Var#1 and put answer|
|                     | |           |   into Var#1                            |
| RandomVariable      |2|Var# Number| Set Var# to a random value between 0 and|
|                     | |           |   Number                                |
|_____________________|_|___________|_________________________________________|

                                                                            124



                ____________________________________________
 ______________|   MISCELLANEOUS ACTION TOKENS - CONTINUED  |_________________
|              |____________________________________________|                 |
|                      NUMBER/TYPES                                           |
| TOKEN NAME           OF PARAMETERS              EXPLANATION                 |
|_____________________________________________________________________________|
| MakeVarRoomNum      |1|Var#       | Set Var# to current room number         |
| MakeVarNounNum      |1|Var#       | Set Var# to number of current noun      |
| MakeVarObjectNum    |1|Var#       | Set Var# to number of current object    |
| GoToVariableRoom    |1|Var#       | Send player to room number in Var#      |
| SendToVariableRoom  |2|Num Var#   | Send Noun number num to room number     |
|                     | |           |   in Var#                               |
| GetVariableIt       |1|Var#       | Get noun number in Var#                 |
| PrintVariableMessage|1|Var#       | Print message number in Var#            |
| NounToVariable      |1|Var#       | Set Var# to literal value of noun       |
| ObjectToVariable    |1|Var#       | Set Var# to literal value of object     |
| WinGame             |0|None       | Player wins game at end of turn         |
| EndGame             |0|None       | Game ends at end of turn                |
| QuitThisCMD         |0|None       | Quit evaluating this CMD                |
| QuitAllCMDs         |0|None       | Finished with all meta-commands         |
| DoneWithTurn        |0|None       | All Done this turn -- get input next    |
| ReDirectTo          |0|None       | See explanation in manual.              |
|_____________________|_|___________|_________________________________________|

                                                                            125

APPENDIX D:  AGT ERROR MESSAGES


ERRORS DURING GAME COMPILATION

Error: "VERB is not a valid verb" -- VERB is not a standard AGT verb, 
nor has it been defined (so far) as a synonym for another verb.  This
error is in the *.DAT file.

Error: ">>> Ignored: ASCII text" -- ASCII text encountered during
reading of  *.DAT file.  Text does not correspond to anything normally
expected in  this file.  Probably, just a comment by the game designer.

Error: "FOR COMMAND VERB NOUN OBJECT -- MAXIMUM DATA SIZE" -- This 
meta-command is too big.  i.e., too many conditions and actions.  Break
into two separate commands for VERB NOUN OBJECT.  One COMMAND right
after the other.  This is a game designer error.

Error: "Too many commands -- Processing halted" -- AGT only allows 400
meta-commands.  The current meta-command being read from the  *.CMD file
would have been number 401.  This is a game designer error.

Error: "FOR COMMAND VERB NOUN OBJECT -- ILLEGAL VERB" -- This
meta-command has a VERB which the parser does not recognize as a
standard AGT verb, a custom verb or a synonym for a valid verb.  This is
a game designer error.

Error: "FOR COMMAND VERB NOUN OBJECT -- ILLEGAL NOUN or OBJECT" -- This
meta-command has a NOUN or OBJECT which the parser does not recognize as
a standard AGT noun or a synonym for a valid noun.  This is a game
designer error.

Error: "FOR COMMAND VERB NOUN OBJECT -- ILLEGAL TOKEN" -- This meta-com-
mand has something in it that the program does not recognize as a token. 
Probably, a game designer comment or a spelling mistake.


ERRORS DURING RESTORING GAME

Error: "File not found, can't restore FileName" -- FileName is not on
disk.


ERRORS DURING GAME PLAY

Error: "I don't understand VERB as a verb." -- Try another VERB. 
Probably a spelling mistake.

Error: "I don't understand NOUN as a noun." -- Try another word to
identify this noun.  May be a noun that does not really play a
significant part in the game, i.e., something described in general in
the room description, but not a separate object in the room.  May also

                                                                            126

be a spelling mistake.

Error: "I don't understand PREP as a preposition." -- Try another
preposition.  May be a spelling mistake.

Error: "I don't understand OBJECT as the object of a preposition." --
Try another word to identify this noun.  May be a noun that does not
really play a significant part in the game, i.e., something described in
general in the room description, but not a separate object in the room. 
May also be a spelling mistake.

Error: "Which NOUN do you mean, the ADJ1 NOUN or the ADJ2 NOUN?" -- Two
or more nouns with the same name are present in the current room. 
Specify the one you mean by some phrase that includes the appropriate
NOUN's adjective.

Error :"I don't understand WORD as either a verb or a noun".  Try
another word to convey what you mean.  May be a spelling mistake.

Error: "You need a preposition and an object whenever you try to VERB a
NOUN."  Some verbs require prepositions and objects in order to work
properly.  For example, PLACE BOOK ON THE TABLE is fine, but PLACE BOOK
by itself will generate this error.

Error: "Too many words in command".  AGT allows for a maximum of 12
words in each part of a compound command (i.e., between AND's and
THEN's).  Re-phrase your command to be more succinct.


TURBO PASCAL RUN-TIME ERRORS

In addition to the above errors which are generated by AGT, it is
possible to get errors from Turbo Pascal -- the language in which AGT is
written.  Specifically, you might get the following two run-time errors
from Turbo:

      101  "Disk Write Error" -- You would get this error when there is
           no more room on your disk, i.e., it is full.  This situation
           might occur when (1) you are compiling a game and there is not
           enough room for the various files being created by the COMPILE
           program (i.e., *.D$$, *.DA1, etc) or (2) you trying to save a
           game and there is not enough room on the disk for the data
           being saved.

      203  "Heap Overflow Error" -- You would get this error if your
           computer does not have enough internal memory.  AGT requires a
           computer with at least 384K of available memory -- after
           counting for all of the memory resident or TSR programs.

                                                                            127

APPENDIX E: VALUE RANGES FOR GAME DEFINITIONS


The following are the valid ranges of numbers for nouns, rooms, and
creatures.  DO NOT assign improper numbers to any category, or you will
experience unpredictable (but consistently erroneous) results.

          Player Carrying:     1
          Player Wearing:   1000
          ROOMS:               2   to      199
          NOUNS:             200   to      299
          CREATURES:         300   to      399

In addition, if the game designer is also using meta-commands, then the
following valid ranges are appropriate:

          FLAGS              1     to      255
          COUNTERS           1     to       25
          VARIABLES          1     to       25
          QUESTIONS          1     to       25
          MESSAGES           1     to      250
          META-COMMANDS      1     to      400


                                                                            128

APPENDIX F: MACINTOSH AND ATARI ST DIFFERENCES

This Appendix summarizes the differences among the Macintosh, Atari ST
and IBM versions of the Adventure Game Toolkit.


MACINTOSH DIFFERENCES


HARDWARE REQUIREMENTS

The Macintosh version requires a Macintosh with at least 512K of memory. 
It has been tested successfully on a Mac 512, a Mac SE and a Mac II.


AGT FILES AND FILE NAMES

      A.   The Macintosh version of AGT uses the files "AGT Run" and "AGT
           Compile", rather than the IBM's RUN.EXE and COMPILE.EXE.  AGT
           Run and AGT Compile are executed by double-clicking on their
           icons.  The other AGT game files needed to run or compile
           should be in the same folder with AGT Run or AGT Compile.

      B.   The Macintosh version of AGT does not use a "batch" file,
           i.e., a *.BAT file, to start playing a particular game. 
           Instead, the Macintosh version will look in the current folder
           for the appropriate adventure game files and present them in a
           list within a normal Macintosh dialog box.  You then indicate
           your choice by double-clicking on the appropriate file.

      C.   All other AGT file naming conventions should be the same in
           either the IBM or Macintosh versions of AGT.  Specifically,
           when compiling a game named ELF, the program AGT Compile will
           look for the files ELF.DAT, ELF.CMD, and ELF.MSG.  AGT Compile
           will then create the files ELF ADVENTURE, ELF.DA1, ELF.DA2,
           etc. -- much like the IBM version.  AGT Run will look for
           these compiled files (ELF ADVENTURE, ELF.DA1, etc.) to play
           the ELF adventure.


QUICK START AT PLAYING ONE OF THE GAMES

Here are the steps to follow in order to make a Macintosh playable copy
of CAVE (the AGT version of the famous "Colossal Cave" adventure game).

      A.   Create a folder named CAVE GAME.  Put the file COMPILE in that
           folder with the CAVE game source files: CAVE.DAT, CAVE.MSG and
           CAVE.CMD.

      B.   Make the CAVE GAME folder the active window, then double-click
           on the AGT Compile icon.  The program will begin execution and
           present you with a dialog box and ask you to select game you

                                                                            129

           wish to compile.  Double-click on CAVE.DAT.  The AGT Compile
           program will then create the files: CAVE ADVENTURE, CAVE.DA1,
           CAVE.DA2, CAVE.DA3 and CAVE.DA5 in the same folder.

      C.   Then either create a new folder or continue to use the CAVE
           GAME folder. Make sure the folder you plan to play the game in
           contains the following files:

                RUN
                CAVE.TTL
                CAVE.INS
                CAVE ADVENTURE
                CAVE.DA1
                CAVE.DA2
                CAVE.DA3
                CAVE.DA5
                ORDERFRM.AGT

           Make the folder with these files in it the active window, then
           double-click on the AGT Run icon to begin play.  When asked
           which game you wish to play (via a dialog box) select CAVE
           ADVENTURE and double-click on it to begin playing the
           adventure.


OPTION AND COMMAND/APPLE KEYS

It is possible to use various key combinations as short-cuts to input
many frequently used adventure game commands and directions. 
Specifically, by holding the OPTION key or holding the COMMAND/APPLE
key, the following short-cut inputs are available:

           OPTION KEY                COMMAND OR APPLE KEY

             1 - GET                  1 - SOUTHWEST
             2 - DROP                 2 - SOUTH
             3 - EXAMINE              3 - SOUTHEAST
             4 - READ                 4 - WEST
             5 - OPEN                 5 - WAIT
             6 - CLOSE                6 - EAST
             7 - INVENTORY            7 - NORTHWEST
             8 - LOOK                 8 - NORTH
             9 - SCORE                9 - NORTHEAST
             0 - HELP                 0 - ENTER
                                      . - EXIT
                                      + - DOWN
                                      - - UP

For example, holding the COMMAND (or APPLE) key down and then hitting
the 6 key would cause the command EAST to be input to the game.  Note,
that the direction keys correspond to the relative "compass" directions
or placement of the keys on a numeric keypad.

                                                                            130

COMMAND LINE OPTIONS

The Macintosh version of AGT does not have any command line options.


SCREEN COLORS

Since most Macintoshs are "monochrome" systems, AGT on the Mac operates
in monochrome mode -- even if you are playing the game on a Mac II with
a color monitor.  This means that any COLOR commands in the *.TTL file
or entered from the keyboard will be ignored in the Macintosh version of
AGT.


CREATING YOUR SOURCE DATA FILES

The Macintosh version of AGT assumes that your game source files are
"standard" text files consisting of individual lines of up to 80 ASCII
characters with each line terminated by a carriage return (or a carriage
return and a line feed).  WARNING: For some strange reason, the
Macintosh version "hangs up" whenever it encounters a line greater than
80 characters in an input line when it reads the game source files.  If
you program "hangs", check to see that all of your source lines are 80
characters or less in length.

Acceptable files are normally created by any text or program editor.  In
addition, almost all Macintosh word processing programs have an option
to save files in text or ASCII format.  AGT has been tested successfully
with the Macintosh versions of Microsoft Word, WordPerfect and MacWrite. 
All of these programs are capable of creating adventure game source
files that AGT can read.  If you use a word processor to create your AGT
source files, just remember to select the save file format option that
saves the files as individual lines, each terminated with a carriage
return and with no special formatting characters.


AGT UTILITY PROGRAMS

There are no Macintosh version the AGTNUM utility program.

                                                                            131

ATARI ST DIFFERENCES


HARDWARE REQUIREMENTS

The Atari ST version may be run on either a 520ST or a 1040ST with
either a single or double-sided drive.


AGT FILES AND FILE NAMES


      A.   The ST version uses the files RUN.TTP and COMPILE.TTP, rather
           than the .EXE files on the PC.  Execute the programs by
           double-clicking on the icon, entering the eight-character game
           name into the dialog box, and either clicking on the OK button
           or pressing <Return>.  Running from a Command Line Interface
           (CLI) will vary with the CLI being used, so check the CLI
           documentation for the method.  The RUN.TTP and COMPILE.TTP
           files should be in the same directory as the game data/run
           files.
 
      B.   All other AGT naming conventions apply as in the PC and
           Macintosh  versions.


FUNCTION AND KEY PAD KEYS

It is possible to use various key combinations to input many
frequently-used adventure game commands and directions.  The following
short-cut inputs are available:

         Function Keys        Cursor Keys          Keypad

         <F1> Get             <Up>     North       <-> Up
         <F2> Drop            <Down>   South       <+> Down
         <F3> Examine         <Left>   West
         <F4> Read            <Right>  East
         <F5> Open            <Insert> Enter
         <F6> Close           <Home>   Exit
         <F7> Inventory       <Help>   (guess!)
         <F8> Look
         <F9> Score


COMMAND LINE OPTIONS

The Command Line options in the ST version should behave as they do for
the PC version, where possible, and not limited by OS or hardware
differences.


                                                                            132

CREATING YOUR SOURCE DATA FILES

The Atari ST version of AGT assumes that your game source files are
"standard" text files consisting of individual lines of up to 80 ASCII
characters with each line terminated by a carriage return (or a carriage
return and a line feed).  Acceptable files are normally created using
any program or text editor.  In addition, almost all Atari ST word
processing programs have an option to save files in text or ASCII
format.  AGT has been tested successfully with a variety of word
processors.  All of these programs were capable of creating adventure
game source files that AGT could read, compile and run successfully.  If
you use a word processor to create your AGT source files, just remember
to select the save file format option that saves the files as individual
lines, each terminated by a carriage return (or carriage return and line
feed) and with no special "embedded" formatting characters.

Also, you may notice that some game source files already existing
produce strange characters at times - the reason is that they use the
IBM line drawing/graphics characters to produce displays.  The ST
(unfortunately) has no equivalents for these characters, so they are
translated as well as the ST is able.  It is not perfect.  Therefore,
try to avoid using any special characters, since this will make the
source less transportable between machines (Atari replaced some IBM
characters with some of their own, so what looks good on an ST probably
won't on a PC or Macintosh, just as the reverse is also true).


AGT UTILITY PROGRAMS

AGTNUM has not been converted to run on the Atari ST.

                                                                            133

APPENDIX G: ANNUAL AGT CONTEST

ANNUAL ADVENTURE GAME WRITING CONTEST


Each year, Softworks sponsors an annual contest for the best computer
text adventure game developed using the Adventure Game Toolkit (AGT).

The Annual Adventure Game Toolkit Gamewriting Contest offers a grand
prize of $100 for the best game submitted.  Additional prizes may be
added if the judges decide that more than one entry is outstanding. 
Gamewriters, including the contest winner(s), will also retain all
rights to their games.

"The main purpose of this contest is to encourage people to share the
games they've written using the Adventure Game Toolkit," said Mark
Welch, one of two co-authors of the program.  "A lot of people start to
write a game, and spend quite a few hours on it, but stop before they
really finished the game, or before it's really playable," said Welch. 
"We are hoping that the contest will inspire people to create
full-featured, playable games that can be enjoyed by other adventure
game fans."


PREVIOUS CONTESTS

Softworks has sponsored three prior adventure game writing contests. 
The winner of the first contest was Alice, written by Douglas Asherman
of Oakland, California.  Alice put the player in the role of Alice in
Wonderland, meeting many of the same characters described in Lewis
Carroll's 19th-century book while also adding some humorous 20th-century
perspective.

The 1988 contest winner was A Dudley Dilemma, by Lane Barrow, a Ph.D
candidate at Harvard.  In this game, the player assumes the role of a
Harvard student in his/her quest for knowledge, adventure and a diploma. 
Along the way, the player experiences a student sit-in and meets
panhandlers, MIT students and other bizarre characters roaming Harvard
Square.

Son of Stagefright, by Mike McCauley was the 1989 winner.  In this game,
you play the role of an actor (or actress) trying to get out of an old,
abandoned theater.  This is an adventure game in three "Acts", where
each Act has a different theme and a different challenge.  The game is
fun(ny), frightening and very clever.


CONTEST DETAILS

To be eligible for the contest, entries must be designed using the
Adventure Game Toolkit, and must not have been publicly released before
January 1st of the contest year.  Contest entries must be postmarked by

                                                                            134

December 31st of the contest year and received by Softworks no later
than January 15 of the following year.  For example, the 1990 contest
will consider games written between January 1, 1990 and December 31,
1990 and received by Softworks no later than January 15, 1991.

Judging begins approximately February 1st and the winner is announced in
the spring following the contest year.  The judges consider each game's
originality, cleverness, fiendishness, humor, raw cunning and
professionalism in arriving at their decision about the contest's
winner.

Entries must be submitted on disks for the IBM PC (or compatible
computer), or for the Apple Macintosh or for the Atari ST computer.  AGT
source code for the game must be provided, but will not be publicly
disclosed without the consent of the author.  In addition to the AGT
source code, each entry must be accompanied by a game "walk-thru" or
solution to be used by the contest judges.  A map of the game would also
be very helpful, but is not required.

No purchase or fee is required to enter.  Game authors need not be
registered users of AGT to enter the contest.  Gamewriters, including
the contest winner(s), will also retain all rights to their games --
including the right to copyright and sell their games -- if they wish. 
However, it is "customary" for the contest game authors to allow their
games' source code to be distributed (to registered AGT user only) -- if
their games are judged as one of the "Best of the Contest."

                                                                            135

APPENDIX H: AGT UTILITY DISK FOR IBM

A special disk of four utilities for use with the Adventure Game Toolkit
(AGT) is available from Softworks for $20.  Currently these utilities
ONLY WORK ON IBM OR COMPATIBLE COMPUTERS.  So, if you have a Macintosh
or and Atari ST, you will just have to wait for the utilities to get
"ported" to your machine.  (This may be a long wait.)

The four utilities include (1) a "Big" version of AGT, (2) a "Pop-up"
hint system, (3) a "Pretty Printer" or "Decompiler, and (4) a SCRIPT to
disk program.  Below is a brief explanation of each:


AGT BIG

The "Big" version of the Adventure Game Toolkit is designed to works
just like the "Normal" version.  The only difference is that the "Big"
version allows you to create and play games that are approximately twice
as large as the "Normal" version of AGT.  Needless to say, however, the
"Big" version of AGT will require that your computer have more memory --
specifically, you will need at least 512K of "free" memory (after
accounting for all the various TSRs you may have loaded).

The specific differences between the two versions are shown below:


RANGES:
                              "Normal"                   "Big"
                                AGT                       AGT
                            ============              ============
                            FROM      TO              FROM      TO
                            ----      --              ----      --
         Player                1       1                 1       1
         Wearing            1000    1000              1000    1000
         Rooms                 2     199                 2     299
         Nouns               200     299               300     499
         Creature            300     399               500     699
         Messages              1     250                 1     500


MAXIMUMS:
                              "Normal"                   "Big"
                                AGT                       AGT
                            ============              ============
         MetaCommands           400                       700
         Counters                25                        50
         Variables               25                        50
         Questions               25                        25
         Flags                  255                       255

Included as part of the AGTBIG "package" is a program that can be used
to convert from "Normal" AGT source files to "Big" AGT source files

                                                                            136

automatically.


POPHINT

POPHINT is a system to enable you to create and use "pop-up" or "TSR" or
"ram-resident" hint systems for any Text Adventure Game that can be
played on the IBM.  POPHINT only requires 6K of memory (in normal
operation).

POPHINT is similar in purpose to UHS, the Universal Hint System,
available for IBM as well as most other computer systems.  POPHINT
differs from UHS in that (1) it creates hints that can "pop-up" while
you are playing the game, (2) it is easier to use, and (3) it is only
available for IBM and compatibles.

The POPHINT system contains the following files:

      POPHINT.DOC     --   The complete set of documentation for POPHINT.

      MAKEHINT.EXE --      A program that "Compiles" your Hints into an
                           encrypted file.

      POPHINT.EXE     --   A TSR that "pops-up" your compiled, encrypted
                           Hint file whenever you hit Alt-H.  POPHINT
                           takes as little as 6K of RAM memory (at your
                           option).

      LGOP.TXT  --    A sample Hint file for the Infocom Text Adventure
                      Game "Leather Goddesses of Phobos".


PRETTY PRINTER or DECOMPILER

PRETTY can be used to either "pretty print" AGT source files, or to
create annotated source files when you only have the game's compiled
files (I.E., EVEN WHEN YOU DON'T HAVE THE ORIGINAL SOURCE FILES).  This
last process is known as "decompiling" and programs that do this are
called "decompliers".  So PRETTY can be used either as an AGT decompiler
or as a way to produce nicely formatted source AGT files.

Here are a couple an example:

      Before PRETTY          After PRETTY
      --------------------   --------------------
      ROOM 20                ROOM 20  ; Hippy Room
      Hippy Room             Hippy Room
      SOUTH 17               SOUTH 17  ; Start of Polish Maze
      UP 21                  UP 21  ; Tax Collector's Lair
      LIGHT 230              LIGHT 230  ; LANTERN
      END_ROOM               END_ROOM

                                                                            137

      COMMAND OPEN DOOR      COMMAND OPEN DOOR
      InRoom 212             InRoom 212 ; CLOSED DOOR is here?
      SwapLocations 211 212  SwapLocations 211 212 ; Swap OPEN and CLOSED DOORS
      PrintMessage 248       PrintMessage 248 ; The door is now open.
      DoneWithTurn           DoneWithTurn
      END_COMMAND            END_COMMAND


SCRIPTER
   
SCRIPTER is another name for a "public domain" program called LPTX,
which allows you to "re-direct" output that would normally go to the
printer and send it to a disk file instead.  It is included in this disk
of utilities because it is useful if you wish to capture your SCRIPTing
output on disk, rather than on your printer.

                                                                            138

Appendix I: ABOUT THE AUTHORS


Mark J. Welch juggles interests in computers, law, and writing by
publishing Law Office Technology Review, a monthly newsletter about
computers for attorneys.  He is also co-author of a weekly computer
column for regional legal newspapers.  In 1989, Welch graduated from the
Boalt Hall School of Law of the University of California at Berkeley,
and is now an attorney in Dublin, California.  He has also worked as an
editor, writer, and reporter for BYTE and InfoWorld magazines, and has
written for dozens of other publications.  He received his B.A. from the
University of Massachusetts at Amherst in 1983 [journalism/interdisciplinary
(computer science)].  Mark is just skilled enough at darts and juggling to
embarrass (and possibly injure) himself and those nearby.


David Malmberg has been active in the world of personal computer since
1977.  He is the author or co-author of seven published software
products.  His most recent software product is P-ROBOTS, which is also
available from Softworks.

His most successful products were the Turtle Graphics series published
by HESware.  These two programs have sold over 80,000 copies world-wide,
were translated into Spanish, and won two Consumer Electronic Software
Showcase awards as some of the best software of 1983.  These programs
are widely used in schools to teach computer literacy to children and
other computer novices.

Dave has also published numerous articles and programs in various
computer magazines.  He has been a Contributing Editor of both
COMPUTE!'s HOME & EDUCATIONAL COMPUTING and MICRO magazines.  He was one
of the principal authors of COMPUTE!'s FIRST BOOK OF VIC, the best
selling computer book of 1983.  He has written regular columns on
educational uses of computers and on LOGO for COMMODORE and POWER/PLAY
magazines.


